Create a Custom Provider

Endpoint URL: /config/low/services/engage-v2 /apps/{appId}/custom-providers



Description

Creates a Custom Provider, a social login provider that wasn’t predefined by Akamai. This endpoint enables you to create a custom provider as long as that provider uses one of the following authentication protocols:

  • Security Assertion Markup Language (SAML 2)
  • OpenID Connect (OIDC)
  • OAuth 2.0

Creating a custom provider by using the /config/low/services/engage-v2/apps/{appId}/custom-providers endpoint means using the POST method and specifying all the properties and property values for the provider as a JSON-formatted body parameter. For example, if you’re creating an identity provider that uses the SAML 2 protocol your body parameter will look similar to the following (note that, in the interests of saving space, we’ve truncated the value of the idp_certificate property:

{
    "title": "GMS SAML",
    "ui": {
        "title": "GMS SAML",
        "icon_url": "https://dyzz9obi78pm5.cloudfront.net/app/image/id/5b749261ec161c506163b298/n/mixi-logo.svg"
    },
    "protocol": "saml2",
    "auth_url": "https://akamai-technologies---assets-46464.login.go.akamai-access.com/saml/idp/sso",
    "idp_certificate": "MIIEAzCCAuugAwIBAgIRAJxc7IHYsUGLrcW5yq4pxVAwDQYJKoZIhvcNAQELBQAwYjENMAsGA1UEAwwEU29oYTEbMBkGA1UECgwSU29oYSBTeXN0ZW1zLCBJbmMuMRIwEAYDVQQHDAlTdW5 =",
    "attribute_map": {
         "/displayName": "/full_name",
         "/email": "/email_address",
         "/name/familyName": "/last_name",
         "/name/givenName": "/first_name",
         "/verifiedEmail": "/email_address"
    }
}

The parameters available to you when creating a custom provider vary depending on whether the new provider uses the SAML 2 protocol or the OpenID Connect/OAuth protocol. The two parameter sets are detailed in the following tables.


OpenID Connect/OAuth Parameters


Parameter

Required

Description

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 
l9fn7g23Jgh7654hVw4idRz9q5N3pOIzFXmBvEEkb9G6232U0u
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"


SAML 2 Parameters


Parameter

Required

Description

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+sb
DANBgkqhkiG9w0BAQsFADAgMR4wHAYDVQQDExV2MS5hcGkudXMuam
i5jb20wHhcNMjAwMjE0MjEwMTAwWhcNMzAwMjExMjEwMTAwWjAgMR
QQDExV2MS5hcGkudXMuamFucmFpbi5jb20wggEiMA0GCSqGSIb3DQ
4IBDwAwgg"

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": ["IIDADCCAeigAwIBAgIRANMwM7
3KbJwvmUggU0OVoXDTMwMDIxMTE5MzU0OVowIDEeMBwGA1UEAxMx
pLnVzLmphbnJhaW4uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCA",
"GkudXMuamFucmFpbi5jb20wHhcNMjAwMjE0MjEwMTAwWhcNMzAw
wMTAwWjAgMR4wHAYDVQQDExV2MS5hcGkudXMuamFucmFpbi5jb20
0GCSqGSIb3DQEBAQUAA4IBDwAwgg"]

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.


URL Parameters

URL parameters that must be included in the request are listed in the following table:

Parameter

Description

customerId

Unique identifier issued to Akamai customers. If you aren’t sure what your Akamai customer ID is, log on to Console and check the value of the customer_id application setting:

appId

Unique identifier of your Social Login application. You can return the IDs of all your Social Login applications by using the GET method and the /engage-v2/apps endpoint.



Respects the API Client Allow List: No


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a configuration client (employing the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. 

For example, if you get back the access token z7S4iEe7KBRG8vMBPWRtJD66VH9SGMAlA56ol-loCln5MZOtGjmcy6O1tSh5lE6t your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer z7S4iEe7KBRG8vMBPWRtJD66VH9SGMAlA56ol-loCln5MZOtGjmcy6O1tSh5lE6t'

If you’re using  Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field:

Note. When requesting an access token, make sure you set the token scope to *:**. Any other scope will result in a 403 Forbidden error when you attempt to use the token.


Sample Request (curl)

The following command creates a custom provider that uses the saml2 protocol:


curl -L -X POST \
  'https://v1.api.us.janrain.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4/v2/config/low/services/engage-v2/apps/fifbclhccfpjdeoejkag/custom-providers' \
  -H 'Authorization: Bearer lCV4idO6TEGHfUYCAqvBKekYWYnGEB7xqDPgOZfwKrhSSWD6B787TpOaGEzxKEAc' \
  -H 'Content-Type: application/json' \
  --data-raw '{
               "title": "GMS SAML",
               "ui": {
                       "title": "GMS SAML",
                       "icon_url": "https://dyzz9obi78pm5.cloudfront.net/app/image/id/5b749261ec161c506163b298/n/mixi-logo.svg"
               },
               "protocol": "saml2",
               "auth_url": "https://akamai-technologies---assets-46464.login.go.akamai-access.com/saml/idp/sso",
               "idp_certificate": "MIIEAzCCAuugAwIBAgIRAJxc7IHYsUGLrcW5yq4pxVAwDQYJKoZIhvcNAQELBQAwYjENMAsGA1UEAwwEU29oYTEbMBkGA1UECgwSU29oYSBTeXN0ZW1zLCBJbmMuMRIwEAYDVQQHDAlTd =",
               "attribute_map": {
                   "/displayName": "/full_name",
                   "/email": "/email_address",
                   "/name/familyName": "/last_name",
                   "/name/givenName": "/first_name",
                   "/verifiedEmail": "/email_address"
               }
}'



Responses

201 Created

If your API call succeeds, you’ll get back the HTTP status code 201 Created. In addition, you’ll get back the URL for the new provider (in the sample response shown below, the ID for the new custom provider, which is included in that URL, is shown in red):

HTTP/2 201 Created
Strict-transport-security: max-age=31536000; includeSubDomains
Trace-id: 056b1679-adda-481a-a93c-443c7ec4705c
Date: Thu, 11 Feb 2021 16:01:29 GMT
Location: https://v1.api.us.janrain.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4/v2/config/low/services/engage-v2/apps/layflfixkxlhgruitref/custom-providers/72f5a17a-3838-4e95-bbc8-5e2e33f0073a

Tip. If you include the -i option when making your Curl command the API response will also include the response headers.

After your API call completes, you can return detailed information for the new provider by using the GET method and the /custom-providers/{providerId} endpoint.


Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code

Description

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.