Guide
TrainingSupportCommunity

Create a custom provider

Suggest Edits

At this point you’re ready to create a custom provider by using the [/customer-providers] operation and the POST method. To do that, you start by configuring a number of properties and property values within the API call’s JSON-formatted request body. The properties and property values you include in that API call vary depending on whether your custom provider uses SAML2, or whether the provider uses either OAuth or OpenID Connect. (SAML2 has fewer required properties than OAuth or OIDC).

Before we go any further, i's important to understand that creating a custom provider typically involves a sort of chicken-and-egg conundrum: to create a authentication client on the social login identity provider you need to include information derived from your new custom provider. However (depending on the protocol you choose), creating a custom provider means including the client ID and client secret of the authentication client. In other words, you can’t do A unless you’ve already done B. But you can’t do B unless you’ve already done A.

So what does that mean? Well, as confusing as it might sound, it just means that you’ll need to use a process similar to this one:

  • Create the authentication client on the social login provider’s site, using placeholder text for the information you need to extract from your custom provider.

  • Create your custom provider, using the requisite information copied from your authentication client you just created.

  • Go back to the authentication client, and replace the placeholder text with the values taken from your custom provider.

So, yes, it sounds complicated. But, as you’re about to see, it’s really pretty easy.

Custom provider properties

The properties available to you when creating a custom provider are listed below:


title

  • OIDC
  • SAML2
  • OAuth

Name used to identify the custom provider. Note that the title is mostly used as a convenience: when referring to an IdP in an API call you’ll use the id property (which can’t be changed) rather than the title property (which can be changed).

For example:

"title": "Akamai OIDC Provider"

ui

  • OIDC
  • SAML2
  • OAuth

Specifies the name and icon displayed on the provider button in the Hosted Login sign-in screen. The ui property is composed of two sub-properties:

  • title. Name of the custom provider as it appears on the sign-in screen. For example, on this provider button the title is Twitter:

    The value assigned to the sub-attribute title does not have to be identical to the value assigned to the primary title (although the two can be identical).

  • icon. URL to the publicly-accessible icon file (.SVG or .PNG) used for the provider button. For example, on the preceding button Twitter’s official bird symbol is used as the icon.

In the request body the ui property is formatted like this:

"ui": {
    "title": "Akamai OIDC Provider",
    "icon_url": "https://akamai.com/oidc/icon.png"
},

protocol

  • OAuth
  • OIDC
  • SAML2

Specifies the authentication protocol used by the identity provider. Allowed values are:

  • openidconnect. Indicates that the identity provider uses the OpenID Connect protocol.
  • saml2. Indicates that the identity provider uses the SAML (Security Assertion Markup Language) 2.0 protocol.
  • oauth2. Indicates that the identity provider uses the OAuth 2.0 protocol.

For example:

"protocol": "openidconnect"

auth_url

  • OAuth
  • OIDC
  • SAML2

URL of the identity provider’s authorization server. For OAuth 2.0 and OpenID Connect, the auth_url can be found by looking at the provider’s developer documentation or, for OIDC only, by looking for the authorization_endpoint entry in the website’s discovery document:

"authorization_endpoint": "https://v1.api.us.janrain.com/00000000-0000-3000-8000-000000000000/login/authorize"

For SAML2 providers, retrieve the provider’s SAML metadata and look in the SingleSignOnService element for the value of the Location attribute

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings
HTTP-POST "Location="https://authorization.identiytdocs.akamai.com/
saml"></SingleSignOnService>

For example:

"auth_url": "https://akamai.com/oidc/authorize"

Note that the auth_url property must use the HTTPS protocol.


token_url

  • OAuth
  • OIDC

URL of the identity provider’s token endpoint. The token_url can be found by looking in the provider’s developer documentation or, for OIDC, by looking for the token_endpoint entry in a website’s discovery document:

"token_endpoint": "https://v1.api.us.janrain.com/00000000-0000-
3000-8000-000000000000/login/token",

For example:

"token_url": "https://akamai.com/oauth/tokens"

Note that the token_url must use the HTTPS protocol.

This member isn’t used with the saml2 protocol.


profile_url

  • OAuth
  • OIDC

URL of the identity provider’s userinfo endpoint (i.e., the endpoint employed for retrieving user profile information). 

The profile_url (which must use the HTTPS protocol) can be found by looking in the provider’s developer documentation or, for OIDC only, by looking for the userinfo_endpoint entry in the website’s discovery document:

"userinfo_endpoint": "https://v1.api.us.janrain.com/00000000-0000-
3000-8000-000000000000/profiles/oidc/userinfo"

For example:

"profile_url": "https://akamai.com/oauth/userinfo"

The profile_url must use the HTTPS protocol.

This member isn’t used with the saml2 protocol.


scopes

  • OAuth
  • OIDC

Specifies the user profile information that can be retrieved from the userinfo endpoint following a successful authentication. The exact scopes available to you depend on the social login provider; standard OIDC scopes include:

  • openid
  • email
  • phone
  • address
  • profile

Keep in mind, however, that individual identity providers might have custom scopes that can be called in addition to (or instead of) the standard scopes. For example, Spotify includes scopes such as:

  • user-read-playback-state
  • user-modify-playback-state
  • user-read-currently-playing

See the IdP’s developer documentation for more information.

Scopes must be specified as a JSON array (i.e., as a comma-separated list enclosed in square brackets). This is always the case, even if you’re only requesting a single scope. 

For example:

"scopes": ["openid","email"]

This member isn’t used with the saml2 protocol.


client_id

  • OAuth
  • OIDC

Unique identifier of the authentication client used for authorization. This client is not one of your Hosted Login login clients. Instead, it’s a client that you create on the identity provider’s developer website. (See this article for a detailed example of what’s involved in creating an authentication client.)

Note that not all IdPs refer to a client or client ID; some providers might reference an application or application ID while others might use the term API client or app.

For example:

"client_id": "6be73a3a-5bf0-4190-a0de-698aa409ff28"

Use the token_auth_method field to control how this member is used with OAuth. This member isn’t used with the saml2 protocol.


client_secret

  • OAuth
  • OIDC

Password/client secret of the authentication client referenced by the client_id member. Again, not all IdPs refer to a client or client secret; some providers might reference an application or application secret while others might use the term API secretor API key.

For example:

"client_secret": "38h-pLUhFXOta3nN3aqIkOtEh0H_WRel9fn7g23JWgp9HVw
4idRz9q5N3pOIzFXmBvEEk79G6232U0utfjh6dn"

Use the token_auth_method field to control how this member is used with OAuth. This member isn’t used with the saml2 protocol.


idp_certificate

  • SAML2

X.509 certificate used by the identity provider to sign a SAML assertion. In a SAML assertion, the encoded certificate is found in the <ds:X509Certificate> section. In the <ds:SignatureValue> section you’ll find the public key, which can be used to verify the authenticity of the assertion.

For example:

"idp_certificate": "MIIC/zCCAeegAwIBAgIQV6EFkhY2gj+sbpdJQAYuyDA
gkqhkiG9w0BAQsFADAgMR4wHAYDVQQDExV2MS5hcGkudXMuamF
ucmFpbi5jb20wHhcNMjAwMjE0MjEwMTAwWhcNMzAwMjExMjEwMT
AwWjAgMR4wHAYDVQQDExV2MS5hcGkudXMuamFucmFpbi5jb20w
ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5K8hPHcB
vYR5qaVQUC5kfLJTDrNm60EUtg4RF9Dgz0Dzo0D+wJ4+IMd+Y4544V
mQj8rqyGwteQAVZP5t1v38PlBWc6ukHoRwOBorM1"

X.509 certificates typically begin with a line that reads -----BEGIN CERTIFICATE----- and end with a line that reads -----END CERTIFICATE-----. Those two lines should not be included in your API call. And don’t include any blank spaces or linefeed characters when entering the certificate value: that’s a guaranteed recipe for failure.

This member isn’t used with the openidconnect or the oauth protocols.


idp_certificate_chain

  • SAML2

JSON array containing a comma-separated list of any additional certificates needed to complete the SAML certificate chain. Because SAML assertions are almost-always self-signed, this property will rarely be required.

For example:

"idp_certificate_chain": ["IIDADCCAeigAwIBAgIRANMwM7cPC3JT63K
bJwvmUggU0OVoXDTMwMDIxMTE5MzU0OVowIDEeMBwGA1UEA
xMVdj","EuYXBpLnVzLmphbnJhaW4uY29tMIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEA1qtx81S7XSvXb6xeflxQbYd3g93
qYhHmqDI85g2rMQL5yT6Q/sZXog2JByTN1fwgmGvrpXqh4Nbyqt+
Y2M47DjEHxto"]

This member isn’t used with the oauth or openidconnect protocols.


attribute_map

  • OAuth
  • OIDC

Maps the user profile values returned from the social login identity provider with their corresponding attributes in the Identity Cloud user profile. For example, a SAML assertion attribute named username might map to the Identity Cloud’s displayName attribute. Although optional, without the attribute_map member you can’t copy information from the user’s social login account to their Identity Cloud account.

For example:

"attribute_map": {
    "/email": "/email_address",
    "/givenName": "/first_name",
    "/familyName": "/last_name"
    }

Note that, in the preceding example, the first value listed (e.g., /givenName) is the name of the Identity Cloud attribute, and the second value (for example, /last_name) is the social login provider attribute.

Currently you can map the following attributes when creating a custom provider:

  • /displayName. User's full name.
  • /email. User's email address,
  • /verifiedEmail. Date and time that the user's email address was verified.
  • /name/familyName. User's last name.
  • /name/givenName. User's first name.
  • /photo. URL that points to a photo of the user.

For more information on the attribute_map member and how to configure it, see Map custom provider attributes.


token_auth_method

  • OAuth

Optional member that specifies the authentication method when making a request to the provider's token endpoint. Allowed values are:

  • client_secret_post. Authentication method in which the client sends authentication information as part of the request body in an HTTP POST. This is the default method and is used if the token_auth_method member is omitted.

  • client_secret_basic. Authentication method which employs the HTTP Basic Authentication Scheme. In this scheme (which should only be used on a secure connection), the client passes a user ID and password to the server as part of an Authorization header.

This member is can only be used with the OAuth protocol.: it can't be used with the openidconnect or the saml2 protocols.


Identifier_attribute

  • OAuth

When working with an OAuth provider, specifies the attribute that uniquely identifies the user. For example, suppose the response from the OAuth IdP includes a unique identifier named userid. In that case, you should set the identifier_attribute to /userid (the preceding forward slash is required). For example:

"identifier_attribute": "/userid"

This member isn’t used with the saml2 or openidconnect protocols.

authn_context

  • SAML2

Enables or disables the RequestedAuthnContext element in SAML requests; when enabled, this element specifically asks the SAML IdP to authenticate users by using a username and password. Often-times this makes no difference, in large part because many SAML IdPs ignore the RequestedAuthnContext element. However, in some cases (Microsoft Azure being a prime example) this element can prevent a user from being authenticated. See Modify the authn_context property for more information.

By default, authn_context is enabled on all SAML providers created prior to August 12, 2021, and disabled for providers created after that date. If necessary, you can disable authn_context by setting the property value to null:

authn_context = null

To enable authn_context (something you probably won't need to do), use this syntax:

"authn_context": {
      "comparison": "exact",
      "class_ref": "PasswordProtectedTransport"
    }

Note that, at the moment, you can only set comparison to exact and you can only set class_ref to PasswordProtectedTransport.

If you have an authn_context-enabled SAML provider and that provider is working as expected, we recommend that you don't disable authn_context. Instead, leave everything exactly as it is, and make a change only if problems arise.

Properties and property values must be included (in JSON format) in the request body of your API call. For example, the request body for a custom provider that uses the OpenID Connect protocol will look similar to this:

{
    "title": "Akamai OIDC Provider",
    "ui": {
        "title": "Akamai OIDC Provider",
        "icon_url": "https://akamai.com/oidc/icon.png"
    },
    "protocol": "oauth",
    "auth_url": "https://akamai.com/oidc/authorize",
    "token_url": "https://akamai.com/oidc/tokens",
    "profile_url": "https://akamai.com/oidc/userinfo",
    "scopes": [
        "openid",
        "email"
    ],
    "client_id": "6be73a3a-5bf0-4190-a0de-698aa409ff28",
    "client_secret": "38h-pLUhFXOta3nN3aqIkOtEh0H_WRel9fn7g23JWgp9HVw4idRz9q5N3pOIzFXmBvEEk79G6232U0utfjh6dn",
    "attribute_map": {
        "/email": "/email_address",
        "/name/givenName": "/first_name",
        "/name/familyName": "/last_name"
    }
}

The request body for a SAML provider might look like this:

{
    "title": "Akamai SAML Provider",
    "ui": {
        "title": "Akamai SAML Provider",
        "icon_url": "https://akamai.com/saml/icon.png"
    },
    "protocol": "saml2",
    "auth_url": "https://akamai.com/saml/authorize",
    "idp_certificate": "MIICzCCAeegAwIBAgIQV6EFkhY2gj+sbpdJQAYuyDANBgkqhkiG9w0BAQsFADAgMR4wHAYDVQQDExV2MS5hcGkudXMuamFucmFpbi5jb20wHhcNMjAwMjE0MjEwMTAwWhcNMzAwMjExMjEwMTAwWjAgMR4wHAYDVQQDExV2MS5hcGkudXMuamFucmFpbi5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5K8hPHcBvYR5qaVQUC5kfLJTDrNm60EUtg4RF9Dgz0Dzo0D+wJ4+IMd+Y4544VmQj8rqyGwteQAVZP5t1v38PlBWc6ukHoRwOBorM1",
    "attribute_map": {
        "/email": "/email",
        "/name/givenName": "/given_name",
        "/name/familyName": "/family_name"
    }
}

In turn, a complete Curl command for creating an OpenID Connect provider will look like the following:

curl -L -X POST \
  --url https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/layflfixkxlhgruitref/custom-providers \
  --header 'authorization: Bearer VIyqpyhe9GWA3UG7_uX5h8jp2zTESwp0QP4R5KwlLFWYMNCOiOySRRtpQTNCrBR- ' \
  --header 'content-type: application/json' \
  --data '{
    "title": "My OpenID Connect IdP",
    "ui": {
        "title": "Acme",
        "icon_url": "https://oidc.akamai.com/icon.png"
    },
    "protocol": "openidconnect",
    "auth_url": "https://oidc.akamai.com/authorize",
    "token_url": "https://oidc.akamai.com/token",
    "profile_url": "https://oidc.akamai.com/userinfo",
    "scopes": [
        "openid",
        "profile",
        "email"
    ],
    "client_id": "339fdbdb-f17c-4ce6-a7d8-0b2c770412de",
    "client_secret": "mCvXRkarZXhL1Zjy5cUqQITpgKz8U7lj8DlauX6iF1wZ0wbnk2FXxD",
    "attribute_map": {
        "/email": "/email_address",
        "/name/givenName": "/first_name",
        "/name/familyName": "/last_name"
    }
}'

Updated 12 months ago