Create a Custom Provider

title

Yes

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

For example:

"title": "Akamai OIDC Provider"

Titles must contain at least 2, but no more than 200, characters.

protocol

Yes

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

• openidconnect. Indicates that the identity provider uses the OpenID Connect protocol.
• oauth2. Indicates that the identity provider uses the OAuth 2.0 protocol.

For example:

"protocol": "openidconnect"

ui

No

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

• title. Name of the custom provider as it appears on the sign-in screen. The value assigned to the title sub-attribute does not have to be identical to the value assigned to the title property (although the two can be identical). Titles must contain at least 2 (but no more than 200) characters.
  
  This property is required if you use the ui parameter.
  
  
• icon. URL to the publicly-accessible image (a .PNG or a .SVG icon file) used on the sign-in screen. 

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

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

attribute_map

No

Maps the user profile attributes returned from the social login identity provider to their corresponding attributes in the Identity Cloud user profile; for example, an OpenID Connect claim named username might map to the Identity Cloud’s displayName attribute. 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 Identity Cloud attribute (e.g., name/givenName) is listed first and the IDP attribute (for example, first_name) is listed second.

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.

auth_url

Yes

URL of the identity provider’s authorization server. For OpenID Connect and OAuth 2.0, the auth_url can be found in the provider’s documentation or, for OpenID Connect, 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"

Note that the auth_url value must use the HTTPS protocol. If it doesn’t your call will fail with an error similar to this:

auth_url scheme must be 'https'

token_url

Yes

URL of the identity provider’s token endpoint. The token_url can be found in the provider’s documentation or, for OpenID Connect, by looking for the token_endpoint entry in the 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/oidc/token"

Similar to the auth_url property, the token_url value must use the HTTPS protocol.

profile_url

Yes

URL of the identity provider’s userinfo endpoint (i.e., the endpoint used for retrieving user profile information). The profile_url can be found in the provider’s documentation or, for OpenID Connect, 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

"title": "https://akamai.com/oidc/userinfo"

The profile_url value must also use the HTTPS protocol.

client_id

Yes

Unique identifier of the identity provider authentication client used for authorization (that is, the client you created on the provider’s developers site). Note that not all providers call this property the client ID; some providers might reference an application ID, an app ID, or an API client ID.

For example:

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

client_secret

Yes

Password/secret of the authentication client referenced in the client_id parameter. Again, not all providers call this a client secret; some providers might reference an application secret or app secret, while others might use the term API secret or API key.

For example:

"client_secret": "645-pLUhFXOta3nN3kitynwtEh0H_WRe 
l9fn7g23Jgh7654hVw4idRz9q5N3pOIzFXmBvEEk 9G6232U0u
tfgrt2"

scopes

No

Specifies the user profile information that can be retrieved from the identity provider’s userinfo endpoint following a successful authentication: the exact scopes available to you depend on the social login provider. Standard OpenID Connect scopes include:

• openid
• email
• phone
• address
• profile

However, many IDPs will have custom scopes instead of (or in addition to) these standard scopes.

Note that scopes must be specified as a JSON array (i.e., as a comma-separated list enclosed in square brackets) even if you’re only requesting a single scope. For example:

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

token_auth_method

No

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 will be used if the token_auth_method parameter is omitted.
  
  
• client_secret_basic. Authentication method which employs the HTTP Basic Authentication Scheme. With 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.

Identifier_attribute

OAuth

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

"identifier_attribute": "/userid"

title

Yes

Name used to identify a custom provider. Note that the title is primarily-used as a convenience: when referring to an individual IdP in an API call, you use the id property (which can’t be changed) instead of the title property (which can be changed).

For example:

"title": "Akamai SAML Provider"

Titles must contain at least 2, but no more than 200, characters.

protocol

Yes

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

• saml2. Indicates that the identity provider uses the Security Assertion Markup Language (SAML) 2 protocol.

For example:

"protocol": "saml2"

ui

No

Specifies the name and icon to be displayed in the Hosted Login sign-in screen. The ui parameter is composed of two sub-properties:

• ·title. Name of the custom provider as it appears on the Hosted Login sign-in screen. The value assigned to the title sub-attribute does not have to be identical to the value assigned to the primary title (although the two can be identical). Titles must contain at least 2, but no more than 200, characters.
  
  This property is required if you use the ui parameter.
  
  
• ·icon. URL to the publicly-accessible image (a .PNG or a .SVC file) used for the custom provider on the sign-in screen. 

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

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

attribute_map

No

Maps the user profile attributes returned from the social login identity provider to 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. 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 Identity Cloud attribute (e.g., name/givenName) is listed first and the IDP attribute (for example, first_name) is listed second.

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 about the attribute_map parameter and how to configure it, see Mapping Attributes.

auth_url

Yes

URL of the identity provider’s authorization server. For SAML 2 providers, you can determine the URL by retrieving the provider’s SAML metadata and looking for the SingleSignOnService element and the Location attribute:

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

For example:

"auth_url": "https://authorization.identitydocs. akamai.com/saml "

The auth_url value must use the HTTPS protocol.

idp_certificate

Yes

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.

When entering the certificate value, be careful not to include any blank spaces or linefeed characters. 

For example:

"idp_certificate": "MIIC/zCCAeegAwIBAgIQV6EFkhY2gj+sbpdJQAYuy 
DANBgkqhkiG9w0BAQsFADAgMR4wHAYDVQQDEx V2MS5hcGkudXMuamFucmFpb
i5jb20wHhcNMjAw MjE0MjEwMTAwWhcNMzAwMjExMjEwMTAwWjAg MR4wHAYD
VQQDExV2MS5hcGkudXMuamFucmFpbi5 jb20wggEiMA0GCSqGSIb3DQEBAQUA
A4IBDwAwgg"

Note: The preceding certificate has been truncated in order to save space.

idp_certificate_chain

No

JSON array containing a comma-separated list of any additional certificates needed to complete the certificate chain. (Make sure that you do not include blank spaces or linefeed characters in any of your certificate values.) This parameter is only required if you use an outside Certificate Authority. If you use a self-signed SAML certificate (as most organizations do), there’s no certificate chain to specify.

For example:

"idp_certificate_chain": ["IIDADCCAeigAwIBAgIRANMwM7cPC3JT63KbJwv 
mUggU0OVoXDTMwMDIxMTE5MzU0OVowIDEeM BwGA1UEAxMVdjEuYXBpLnVzLmphbn
JhaW4uY29t MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB","GkudXMuamFucmFp
bi5jb20wHhcNMjAw MjE0MjEwMTAwWhcNMzAwMjExMjEwMTAwWjAg MR4wHAYDVQQ
DExV2MS5hcGkudXMuamFucmFpbi5 jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwA
wgg"]

Note: The preceding certificates have been truncated in order to save space.

authn_context

No

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.

400

The request was invalid. Typically occurs in one of two instances:

• Your URL is incorrect. Verify each section of the URL and then try again.
• Your body parameter has been configured incorrectly. This is often because the JSON formatting isn’t valid.

403

Forbidden. Access is denied. This typically occurs because your configuration access token has expired. Obtain a new access token and then try again.

404

The requested resource was not found. Typically occurs if your call specifies an invalid customer ID or application ID. Verify that those values are correct and then try again.