Using the /custom-providers Endpoint to Create a Custom Provider

At this point you’re ready to create a custom provider by using the /customer-providers endpoint 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 body parameter. 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).

The properties available to you when creating a custom provider are listed in the following table:

Properties

Supported Protocols

Description

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 fon the provider button. For example, on this button Twitter’s official bird symbol is used as the icon:

In the body parameter 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 parameter 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 parameter 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 parameter 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"

This parameter isn’t used with the saml2 protocol.

client_secret

OAuth
OIDC

Password/client secret of the authentication client referenced by the client_id parameter. 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 secret or API key.

For example:

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

This parameter 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 parameter 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 (note that color coding is used to help you differentiate the two certificates):

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

This parameter 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 parameter you can’t copy information from the user’s social login account to their Identity Cloud account.

For example:

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

Note that, in the preceding example, the first value listed (e.g., /name/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 parameter and how to configure it, see Mapping Attributes.

token_auth_method

OAuth
OIDC

Optional parameter that specifies the authentication method used by the 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 parameter 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 parameter isn’t used with the saml2 protocol.

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 parameter 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 this article 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 but that provider is working as expected, we recommend that you don't disable the 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 body parameter of your API call. For example, the body parameter 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 body parameter 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": "MIIC/zCCAeegAwIBAgIQV6EFkhY2gj+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"
    }
}'