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:
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:
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:
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" Use the token_auth_method field to control how this parameter is used with OAuth. |
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" Use the token_auth_method field to control how this parameter is used with OAuth. |
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:
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 when making a request to the provider's token endpoint. Allowed values are:
This parameter can only be used with the OAuth2 protocol. It isn’t 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, 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:
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:
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:
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:
|
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. |