Oracle Cloud Infrastructure Documentation

Authenticating Using a Custom Social Identity Provider

Configure an identity domain to authenticate using a custom social identity provider (IdP).

You can set up the metadata for a custom social identity provider using the examples below.

The metadata must be posted to /admin/v1/SocialIdentityProviderMetadata.
  • to add a global level provider, invoke the <domainURL>/admin/v1/SocialIdentityProviderMetadata endpoint.
  • To add a tenant level provider, invoke the <idcs-oracle-url>/admin/v1/SocialIdentityProviderMetadata endpoint.
Note

If custom social identity providers with same name have been defined using SocialIdentityProviderMetadata at both global and tenant level, the custom social identity provider defined at the tenant level takes precedence.
After the metadata has been loaded, you can create the new identity provider:
  • By choosing it from the Console. Choose Security, then Identity Providers, then Add Social IdP and choose the new identity provider.
  • From the /admin/v1/SocialIdentityProviders REST API.

The new custom social identity provider is available as one of the Social Identity Provider Types.

Custom Social Identity Provider Login Use Cases

These login use cases show how to change the AuthorizePhase, loginScopes, tokenPhase, and userInfoPhase depending on the provider.

In these samples, Expressions (starting with $) refer to the parameter values that aren't constant:

  • $socialIdentityProvider represents the corresponding SocialIdentityProvider resource. For example, $socialIdentityProvider.consumerKey refers to the client secret configured in the tenant specific social identity provider profile.
  • ${state} is the state generated by the identity domains runtime while sending the Authorize request to the social IdP.
  • ${redirectUri} is the tenant-specific callback URL generated by identity domain runtime.
  • ${scope} refers to:
    • In the login use-case, the scope string specified as value of the loginScopes attribute.

    • In the provisioning use-case, the scope string specified as value of the provisioningScopes attribute.

  • ${clientCredentials} is the standard base-64 encoded representation of client id and client secret as required in the authorization header for Basic authentication scheme.
  • ${authorizationCode} refers to the authorization code received with callback from the social IdP.

In the following sections, there's sample metadata for the login use case, followed by two examples. Then the sample metadata for the provisioning use case.

Custom Social Identity Provider Login Sample Metadata

{
	"type": "SampleProviderForLogin",
	"status": "enabled",
	"idAttribute": "email",
	"capabilities": [
		"login"
	],
	"authorizePhase": {
		"loginScopes": "<scope string>",
		"url": "<Authorization endpoint>"
	},
	"authorizePhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "code",
			"name": "response_type"
		},
		{
			"value": "${scope}",
			"name": "scope"
		},
		{
			"value": "${state}",
			"name": "state"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		}
	],
	"tokenPhase": {
		"url": "<Token endpoint>",
		"method": "<HTTP method for Token endpoint - get/post>"
	},
	"tokenPhaseHeaders": [
		{
			"value": "application/json",
			"name": "Accept"
		},
		{
			"value": "Basic ${clientCredentials}",
			"name": "Authorization"
		}
	],
	"tokenPhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "${socialIdentityProvider.consumerSecret}",
			"name": "client_secret"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		},
		{
			"value": "${authorizationCode}",
			"name": "code"
		},
		{
			"value": "authorization_code",
			"name": "grant_type"
		}
	],
	"userInfoPhase": {
		"url": "<UserInfo endpoint>",
		"method": "<HTTP method for UserInfo endpoint - get/post>"
	},
	"userInfoPhaseHeaders": [
		{
			"value": "*/*",
			"name": "Accept"
		},
		{
			"value": "token ${accessToken}",
			"name": "Authorization"
		}
	],
	"userInfoPhaseParameters": [
		{
			"name": "access_token",
			"value": "${accessToken}"
		}
	],
	"userInfoAttributeMappings": [
		{
			"idpAttribute": "firstname",
			"idcsAttribute": "given_name"
		},
		{
			"idpAttribute": "lastname",
			"idcsAttribute": "family_name"
		},
		{
			"idpAttribute": "email.primary",
			"idcsAttribute": "email"
		}
	],
	"iconUrl": "<icon url>",
	"schemas": [
		"urn:ietf:params:scim:schemas:oracle:idcs:SocialIdentityProviderMetadata"
	]
}

Custom Social Identity Provider GitHub Example

{
	"type": "GitHub",
	"status": "enabled",
	"idAttribute": "email",
	"capabilities": [
		"login"
	],
	"authorizePhase": {
		"loginScopes": "user user:email",
		"url": "http://github.com/login/oauth/authorize"
	},
	"authorizePhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "code",
			"name": "response_type"
		},
		{
			"value": "${scope}",
			"name": "scope"
		},
		{
			"value": "${state}",
			"name": "state"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		}
	],
	"tokenPhase": {
		"url": "https://github.com/login/oauth/access_token",
		"method": "post"
	},
	"tokenPhaseHeaders": [
		{
			"value": "application/json",
			"name": "Accept"
		},
		{
			"value": "Basic ${clientCredentials}",
			"name": "Authorization"
		}
	],
	"tokenPhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "${socialIdentityProvider.consumerSecret}",
			"name": "client_secret"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		},
		{
			"value": "${authorizationCode}",
			"name": "code"
		},
		{
			"value": "authorization_code",
			"name": "grant_type"
		}
	],
	"userInfoPhase": {
		"url": "https://api.github.com/user",
		"method": "get"
	},
	"userInfoPhaseHeaders": [
		{
			"value": "*/*",
			"name": "Accept"
		},
		{
			"value": "token ${accessToken}",
			"name": "Authorization"
		}
	],
	"userInfoPhaseParameters": [
		{
			"name": "access_token",
			"value": "${accessToken}"
		}
	],
	"userInfoAttributeMappings": [
		{
			"idpAttribute": "name",
			"idcsAttribute": "given_name"
		}
	],
	"iconUrl": "<<iconURL>>",
	"schemas": [
		"urn:ietf:params:scim:schemas:oracle:idcs:SocialIdentityProviderMetadata"
	]
}

Identity Domains as an Identity Provider (with username Mapping)

Set email as optional in identity domains using a patch operation in https://{{host}}/admin/v1/IdentitySettings/IdentitySettings.

{
    {
    "schemas": 
		[
            "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ],
    "Operations": 
        [
            {
                "op": "replace",
                "path": "primaryEmailRequired",
                "value": false
            }
        ]
    }
}

Example: 

{
	"type": "IDCSProvider",
	"status": "enabled",
	"idAttribute": "preferred_username",
	"capabilities": [
		"login"
	],
	"authorizePhase": {
		"loginScopes": "openid profile email",
		"url": "https://idcs-idp-where-login-happen.identity.oraclecloud.com/oauth2/v1/authorize"
	},
	"authorizePhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "code",
			"name": "response_type"
		},
		{
			"value": "${scope}",
			"name": "scope"
		},
		{
			"value": "${state}",
			"name": "state"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		}
	],
	"tokenPhase": {
		"url": "https://idcs-idp-where-login-happen.identity.oraclecloud.com/oauth2/v1/token",
		"method": "post"
	},
	"tokenPhaseHeaders": [
		{
			"value": "application/x-www-form-urlencoded",
			"name": "Content-Type"
		},
		{
			"value": "Basic ${clientCredentials}",
			"name": "Authorization"
		}
	],
	"tokenPhaseParameters": [
		{
			"value": "${authorizationCode}",
			"name": "code"
		},
		{
			"value": "authorization_code",
			"name": "grant_type"
		}
	],
	"userInfoPhase": {
		"url": "https://idcs-idp-where-login-happen.identity.oraclecloud.com/oauth2/v1/userinfo",
		"method": "get"
	},
	"userInfoPhaseHeaders": [
		{
			"value": "application/x-www-form-urlencoded",
			"name": "Content-Type"
		},
		{
			"value": "Bearer ${accessToken}",
			"name": "Authorization"
		}
	],
	"userInfoPhaseParameters": [
		{
			"name": "access_token",
			"value": "${accessToken}"
		}
	],
	"schemas": [
		"urn:ietf:params:scim:schemas:oracle:idcs:SocialIdentityProviderMetadata"
	]
}

Custom Social Identity Provider Okta Example

{
	"type": "OktaTest",
	"status": "enabled",
	"idAttribute": "email",
	"capabilities": [
		"login"
	],
	"authorizePhase": {
		"loginScopes": "openid profile email",
		"url": "<Okta's UserInfo endpoint>"
	},
	"authorizePhaseParameters": [
		{
			"name": "client_id",
			"value": "${socialIdentityProvider.consumerKey}"
		},
		{
			"name": "response_type",
			"value": "code"
		},
		{
			"name": "scope",
			"value": "${scope}"
		},
		{
			"name": "state",
			"value": "${state}"
		},
		{
			"name": "redirect_uri",
			"value": "${redirectUri}"
		}
	],
	"tokenPhase": {
		"url": "<Okta's UserInfo endpoint>",
		"method": "post"
	},
	"tokenPhaseHeaders": [
		{
			"value": "application/json",
			"name": "Accept"
		}
	],
	"tokenPhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "${socialIdentityProvider.consumerSecret}",
			"name": "client_secret"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		},
		{
			"value": "${authorizationCode}",
			"name": "code"
		},
		{
			"value": "authorization_code",
			"name": "grant_type"
		}
	],
	"userInfoPhase": {
		"url": "<Okta's UserInfo endpoint>",
		"method": "post"
	},
	"userInfoPhaseHeaders": [
		{
			"value": "*/*",
			"name": "Accept"
		},
		{
			"value": "Bearer ${accessToken}",
			"name": "Authorization"
		}
	],
	"iconUrl": "<<iconURL>>",
	"schemas": [
		"urn:ietf:params:scim:schemas:oracle:idcs:SocialIdentityProviderMetadata"
	]
}

Custom Social Identity Provider Sample Metadata (for Provisioning Use Case)

{
	"type": "SampleProviderForProvisioning",
	"status": "enabled",
	"capabilities": [
		"provisioning"
	],
	"authorizePhase": {
		"provisioningScopes": "<scope string>",
		"url": "<Authorization endpoint>"
	},
	"authorizePhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "code",
			"name": "response_type"
		},
		{
			"value": "${scope}",
			"name": "scope"
		},
		{
			"value": "${state}",
			"name": "state"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		}
	],
	"tokenPhase": {
		"url": "<Token endpoint>",
		"method": "<HTTP method for Token endpoint - get/post>"
	},
	"tokenPhaseHeaders": [
		{
			"value": "application/json",
			"name": "Accept"
		},
		{
			"value": "Basic ${clientCredentials}",
			"name": "Authorization"
		}
	],
	"tokenPhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "${socialIdentityProvider.consumerSecret}",
			"name": "client_secret"
		},
		{
			"value": "${redirectUri}",
			"name": "redirect_uri"
		},
		{
			"value": "${authorizationCode}",
			"name": "code"
		},
		{
			"value": "authorization_code",
			"name": "grant_type"
		}
	],
	"refreshTokenPhaseHeaders": [
		{
			"value": "application/json",
			"name": "Accept"
		}
	],
	"refreshTokenPhaseParameters": [
		{
			"value": "${socialIdentityProvider.consumerKey}",
			"name": "client_id"
		},
		{
			"value": "${socialIdentityProvider.consumerSecret}",
			"name": "client_secret"
		},
		{
			"value": "${refreshToken}",
			"name": "refresh_token"
		}