Guide

Create a social login provider

Suggest Edits

Social login requires you to create an authentication client (also referred to as an app or an application) for use with your social login provider. This involves the same process used with the social login IdPs predefined by ​Akamai​; for example, before you can use Twitter for social login you need to create an authentication client for Twitter. 

The exact steps for creating an authentication client vary depending on: 1) the social login provider; and, 2) whether you’re creating a SAML, an OpenID Connect, or OAuth 2.0 client. Because of this, we can’t provide a step-by-step guide for every possible social login identity provider. However, we do have a sample walkthrough that takes you through the process of creating an app on one such provider. In addition, the following sections of this documentation details the information you’ll need to provide when creating an authentication client for a SAML IdP, or when creating an authentication client for an IdP that uses either OAuth 2,0 or OpenID Connect.


📘

This document includes a number of URLs, such as redirect URLs, that you must construct yourself. None of the Custom Provider APIs will build these URLs for you. (On the bright side, and as you'll see, constructing these URLs is very easy.)


Create an authentication client for a SAML2 identity provider

When creating an authentication client for a SAML2 identity provider, you’ll need to have the following two pieces of information handy:


Your ACS URL

The ACS (Assertion Consumer Service) URL specifies the page where the SAML server response should be sent. As that definition makes plain, the ACS URL is really just a fancy name for the SAML redirect page.


📘

Different IdPs might use different terminologies when referencing this URL; instead of ACS URL you might see terms like Single Sign On URL, Callback URL, or Direct Relay State.


If your social login application uses a standard realm, your ACS URL must look similar to this:

https://identitydocs.rpxnow.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4.ab34fd29-1c4b-42e3-8be8-142ab8de8841/callback

In the preceding URL:

  • identitydocs is your realm name. When using a standard realm, the realm name must be followed by .rpxnow.com.

  • 3cc14467-fd4f-437d-a0c0-0b3888dd2ee4 is your ​Akamai​ customer ID.

  • ab34fd29-1c4b-42e3-8be8-142ab8de8841 is your custom provider’s provider ID. If you don’t have this value when you create the authentication client, that’s fine: use a placeholder value and then, after you create the custom provider, go back and edit the placeholder text. Note that there’s a period (.) between the customer ID and the provider. That’s very important.

And don’t forget the /callback tacked on the end of the URL. That’s important: without that, you’ll be able to authenticate with the social login IdP, but you won’t be able to authenticate with Hosted Login.

If you have a custom realm (i.e., identitydocs.akamai.com) you ACS URL will look like this:

https://identitydocs.akamai.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4.ab34fd29-1c4b-42e3-8be8-142ab8de8841/callback

It’s probably worth repeating that your ACS URL must use one of these two formats (which format depends on whether you’re using a custom realm or the standard realm). After authenticating with the SAML provider, the user must be redirected to a page that knows how to parse (and how to make use of) a SAML assertion. That means that, if you don’t send the user to your ACS URL, Hosted Login authentication fails.


Your entity ID

Also referred to as the Audience Restriction, the Audience URL, or the Issuer. If you have a standard realm (e.g., identitydocs) then your entity ID will look like this (note that the HTTPS protocol is a required part of the ID):

https://identitydocs.rpxnow.com

If you have a custom realm (e.g., identitydocs.akamai.com) then your entity ID will simply be the realm name plus the HTTPS protocol:

https://identitydocs.akamai.com

That's the information you'll need to create an authentication client. After you’ve created the client on the social login provider, you’ll have to retrieve the following information and use it to update your custom provider:

  • The authentication client’s authorization URL (also known as the SSO URL).
  • The authentication client’s signing certificate.

Create an authentication client for an OpenID Connect/OAuth 2.0 identity provider

To create an authentication client that uses OpenID Connect or OAuth 2.0, you need to know your custom provider’s redirect URL. If you’re using a standard realm, that redirect URL will look similar to this:

https://identitydocs.rpxnow.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4.ab34fd29-1c4b-42e3-8be8-142ab8de8841/callback

In the preceding URI:

  • identitydocs is the name of your realm.

  • 3cc14467-fd4f-437d-a0c0-0b3888dd2ee4 is your ​Akamai​ customer ID.

  • ab34fd29-1c4b-42e3-8be8-142ab8de8841 is the id of your custom provider. Note that there’s a dot (.) between the customer ID and the provider ID.

Similar to the SAML ACS URL, your redirect URL must end with /callback.

If you’re using a custom realm (e.g., identitydocs.akamai.com), use the full realm name in the redirect URL:

https://identitydocs.akamai.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4.ab34fd29-1c4b-42e3-8be8-142ab8de8841/callback

It’s important to note that your redirect URL must be formatted using the preceding guidelines. As a general rule, OAuth and OIDC allow you to redirect users to any location on the web. In this case, however, the user must be redirected to a page that understands how to process the API response returned by a social login provider. If you redirect your users somewhere else, those users will be logged on to the social login IdP but they won’t get logged on to Hosted Login.

Updated about 1 year ago