Managing Identity Providers

You can set up federated login between an identity domain and external identity provider. This allows users to sign in and access Oracle Cloud Infrastructure resources by using existing logins and passwords managed by the identity provider.

Required Policy or Role

To manage identity domain security settings and identity providers, you must have one of the following access grants:
  • Be a member of the Administrators group
  • Be granted the Identity Domain Administrator role or the Security Administrator role
  • Be a member of a group granted manage identity-domains permissions

To understand more about policies and roles, see The Administrators Group, Policy, and Administrator Roles, Understanding Administrator Roles, and Understanding Policies.

About Identity Providers and Service Providers

An identity provider, also known as an authentication authority, provides external authentication for users who want to sign in to an identity domain using their external provider’s credentials. While an identity domain can serve as an identity provider to a third-party service provider, in this context where it relies on an identity provider to authenticate users that access the identity domain, the identity domain is the service provider. More generally, you can also think of Oracle Cloud Infrastructure as the service provider because it provides the services and resources that users want access to.

For example, your organization may want users to sign in and gain access to Oracle Cloud Services by using their Microsoft Active Directory Federation Services (AD FS) credentials. In this case, Microsoft AD FS acts as the identity provider (IdP) and the identity domain functions as the service provider (SP). MS AD FS authenticates the user and returns a token containing identity and authentication information to the identity domain (for example, the user name and the email address of the user). This security token is digitally signed by the IdP. The SP verifies the signature on the token and then uses the identity information to establish an authenticated session for the user. This is known as federated single sign-on where a user is challenged for credentials in one domain and is granted access to another domain.

About Digital Certificates

A digital certificate is like an electronic passport that helps a person, computer, or organization to exchange information securely over the internet using public key cryptography. A digital certificate may be referred to as a public key certificate.

Just like a passport, a digital certificate provides identifying information, is forgery resistant, and can be verified because it is issued by an official, trusted agency. The certificate can contain the name of the certificate holder, a serial number, expiration dates, a copy of the certificate holder's public key (used for encrypting messages and verifying digital signatures) and the digital signature of the certificate-issuing authority (CA) so that a recipient can verify that the certificate is real.

In order to verify external identity providers’ signatures, the service provider stores copies of their signing certificates. When the service provider receives a signed message from an identity provider, before the stored certificate is used to verify the signature, the certificate must be verified as valid. Certificate validation includes verifying that the certificate has not expired. After the certificate has been validated, the certificate is used to verify the signature on the message.

In order for this operation to succeed, the public key embedded in the certificate must match the private key that the identity provider used to sign the message.

What Happens When an Identity Provider's Certificate Expires?

If an identity provider's signing certificate expires, then certificate validation will fail, and the identity domain is unable to complete single sign-on (SSO) operations for that identity provider's users. Therefore, when an identity provider's certificate nears its expiration date, you must make plans to replace it. The typical process is a follows:
  1. Obtain the new signing certificate from the identity provider. This may be published by the identity provider for self-service download, or you may need to contact the identity provider administrator.
  2. Load the new signing certificate into the identity domain configuration for the identity provider.
  3. If the identity provider has also rolled over its signing private/public key pair (rather than only reissuing a new certificate for the existing key pair), then you must update the identity provider configuration to begin using the new keys to sign messages. Again, this may be self-service or require coordination with the identity provider administrator.
Note

If the identity provider rolls over its signing key pair, then SSO will fail during the period of time between Step 2 and Step 3 above. For this reason, the certificate update is typically coordinated between the identity provider and identity domain administrators.

About SAML Just-In-Time Provisioning

SAML Just-In-Time (JIT) Provisioning automates user account creation when the user first tries to perform SSO and the user doesn't yet exist in the identity domain. In addition to automatic user creation, JIT allows granting and revoking group memberships as part of provisioning. JIT can be configured to update provisioned users so the users’ attributes in the service provider (SP) store can be kept in sync with the identity provider (IdP) user store attributes.

Benefits

The advantages of JIT are:
  • The footprint of user accounts in the identity domain is limited to those users who actually sign in through federated SSO, rather than all users in the IdP's user directory.
  • Reduced administrative costs as accounts are created on demand as part of the SSO process and the identity provider and service provider user stores don't have to be synchronized manually.
  • Any new users added later to the identity provider user store won't require administrators to create corresponding service provider accounts manually (users will always be in sync).

How It Works

There are four runtime flows for JIT Provisioning:
When Signing In, The User: Flow
Exists in the SP and JIT provisioning is enabled. Normal SSO flow.
Doesn't exist in the SP and JIT provisioning is not enabled. Normal SSO failure flow.
Doesn't exist in the SP and JIT create user is enabled. User is created, and populated with the SAML assertion attributes, as mapped in the JIT configuration.
Exists in the SP and JIT update is enabled. User attribute values are updated with the SAML assertion attributes, as mapped in the JIT configuration.

Configuring SAML JIT Provisioning

SAML JIT Provisioning can be configured using the Console or /admin/v1/IdentityProviders REST API endpoint. See the following references to configure SAML JIT Provisioning:

Using the Console

Adding a SAML Identity Provider

Use the Console to add a SAML 2.0 identity provider (IdP) to an identity domain so authenticated users from the IdP can access Oracle Cloud Infrastructure can access resources and cloud applications.

Common terms

Identity Provider (IdP)

An IdP is a service that provides identifying credentials and authentication for users.

Service Provider (SP)

A service (such as an application, website, and so on) that calls upon an IdP to authenticate users.

Use the following steps to create a SAML 2.0 IdP:

Entering SAML Identity Provider details

Entering SAML identity provider details.

  1. Navigate to the identity domain: Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Click Add IdP, and then click Add SAML IdP.
  4. Enter the following information:
    • Name: Enter the name of the IdP.
    • (Optional) Description: Enter a description of the IdP.
    • (Optional) Identity provider icon: Drag and drop a supported image, or click select one to browse for the image.
  5. Click Next.
  6. On the Exchange metadata screen, click Export SAML metadata button to send the SAML metadata to the identity provider. Do one of the following:
    • Import IdP metadata: Select this option if you have an XML file exported from your IdP. Drag and drop the XML file to upload the metadata, or click select one to browse for the metadata file.
    • Enter IdP metadata: Select this option if you want to manually enter the IdP metadata. Provide the following details:
      • Identity provider issuer URI
      • SSO service URI
      • SSO service binding
      • Upload identity provider signing certificate
      • Enable global logout
    • Import IdP URL: Enter the URL of your IdP metadata.
  7. Click Show advanced options if you want to select the following:
    • Signature hashing algorith: Select SHA-256 or SHA-1
    • Require encrypted assertion: Indicates that the identity domain authorization expects an encrypted assertion from the IdP.
    • Force authentication: Select this option to require users to authenticate with the IdP, even if the session is still valid.
    • Requested authentication context: Select authentication content class references.
    • Holder-of-Key subject confirmation required: Available after you upload a Holder-of-Key (HOK) supported valid metadata file.
    • Send signing certificate with SAML message: Select this to include the identity domain's signing certificate with SAML messages sent by your identity domain. Some SAML providers require the signing certificate to look up the SAML partner configuration.
  8. Click Next.
  9. On the Exchange metadata screen, click Export SAML metadata button to send the SAML metadata to the identity provider. Do one of the following:
    • Import IdP metadata: Select this option if you have an XML file exported from your IdP. Drag and drop the XML file to upload the metadata, or click select one to browse for the metadata file.
    • Enter IdP metadata: Select this option if you want to manually enter the IdP metadata. Provide the following details:
      • Identity provider issuer URI
      • SSO service URI
      • SSO service binding
      • Upload identity provider signing certificate
      • Enable global logout
    • Import IdP URL: Enter the URL of your IdP metadata.
  10. Click Show advanced options if you want to select the following:
    • Signature hashing algorith: Select SHA-256 or SHA-1
    • Require encrypted assertion: Indicates that the identity domain authorization expects an encrypted assertion from the IdP.
    • Force authentication: Select this option to require users to authenticate with the IdP, even if the session is still valid.
    • Requested authentication context: Select authentication content class references.
    • Holder-of-Key subject confirmation required: Available after you upload a Holder-of-Key (HOK) supported valid metadata file.
    • Send signing certificate with SAML message: Select this to include the identity domain's signing certificate with SAML messages sent by your identity domain. Some SAML providers require the signing certificate to look up the SAML partner configuration.
  11. Click Next.
  12. On the Add SAML identity provider screen, do the following:
    1. Select a Requested Name ID format.
  13. Map user's identity attributes received from the IdP to an Oracle Cloud Infrastructure identity domain.
    Mapping options vary based on identity provider. You might be able to directly assign an IdP value to an Oracle Cloud Infrastructure identity domain value. For example, NameID might map to UserName. If you select SAML assertion attribute as the source, select the Assertion attribute name and then enter the Oracle Cloud Infrastructure identity domain.
  14. Click Submit.
  15. On the Review and create screen, review your SAML identity provider settings. If the settings are correct, click Create. Click Edit next to the set of settings, if you need to change them.
  16. The console displays a message when the SAML identity provider is created. You can do the following from the overview page:
    • Click Test to verify that the SAML SSO connection is working correctly.
    • Click Activate to activate the IdP so the identity domain can use it.
    • Click Assign to IdP policy rule to assign this SAML identity provider to an existing policy rule you have created.
  17. Click Close.
Import Metadata for a SAML Identity Provider
Export SAML Metadata
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Open an identity provider.
  4. Click Export SAML metadata.
  5. Select one of the following:
    • Metadata File: Select download the SAML XML metadata file, or download the SAML XML metadata with self-signed certificates.
    • Manual Export: Manually exporting the metadata allows you to choose from multiple SAML options, for example the Entity ID or Logout response URL. After you copy the export file, you can download the Service provider signing certificate or the Service provider encryption certificate.
    • Metadata URL: If your IdP supports downloading SAML metadata directly. Click Access signing certificate to allow clients to access the signing certificate without having to log into an IdP.
Configuring IdP metadata

Enter IdP metadata details manually, or import a metadata file.

  1. Select one of the following:
    • Import IdP metadata: Select this option if you have an XML file exported from your IdP. Drag and drop the XML file to upload the metadata, or click select one to browse for the metadata file.
    • Enter IdP metadata: Select this option if you want to manually enter the IdP metadata. Provide the following details:
      • Identity provider issuer URI:
      • SSO service URI
      • SSO service binding
      • Upload identity provider signing certificate
      • Upload identity provider encryption certificate
      • Enable global logout
      • Identity provider logout request URL
      • Identity provider logout response URL
      • Logout binding
  2. Select the Signature hashing algorithm method.
  3. Select whether you want to use a Signed signing certificate with SAML message.
  4. Click Next.
Mapping user attributes

Map the relationship between the IdP user attributes and identity domain user attributes.

  1. In the field Requested Name ID format, select a mapping option.

    Mapping options vary based on identity provider. You might be able to directly assign an IdP value to an Oracle Cloud Infrastructure identity domain value. For example, NameID might map to UserName. If you select SAML assertion attribute as the source, select the Assertion attribute name and then enter the Oracle Cloud Infrastructure identity domain.

    If you select Custom, enter the details in the field Custom Name ID format.

  2. Select fields in Identity provider user attribute and select a corresponding field in Identity domain user attribute.
  3. Click Next.
Reviewing and creating the IdP

Verify the IdP options are accurate and then create the IdP.

  1. Click Test login to open the IdP sign-in screen.
  2. Click Create IdP.
    Note

    To edit an IdP after creating it, go to the Identity Providers list, select the IdP, and then edit the IdP.
Adding a Just-in-Time SAML IdP

You can set up a SAML IdP that uses just-in-time (JIT) provisioning.

  1. Navigate to the identity domain: Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Select an identity provider, and then click Configure JIT.
  4. Select Enable Just-in-Time (JIT) provisioning.
  5. Select one of the following:
    • Create new identity domain user: Create an identity user in the identity domain, if the user does not exist when logging in with the identity provider.
    • Update existing identity domain user: Merge and overwrite identity domain user account data from the mapped identity provider. The existing data is overwritten by the user data from the identity provider.
    Note

    JIT will not be enabled if you do not select one of these two options.
  6. In the field Map user attributes, map a user account from the identity provider to a user account from the identity domain.
    1. Click IdP user attribute type.
      • If you select Attribute, then enter the identity provider user attribute name.
      • If you selected NameID, you do not need to enter the identity provider user attribute name.
    2. Select the identity domain user attribute.
    3. (Optional) Add more identity domain attributes.
  7. Click Assign group mapping to enable group mapping. If you enable group mapping, you must include the Group membership attribute name.
  8. To import the group settings, select one of the following:
    • Define explicit group mapping: This option requires you to provide the mapping between the identity provider and identity domain.
    • Assign implicit group mapping: This option maps an identity provider group to an identity domain group that has the same exact name.
    1. If you select explicit grouping: enter the IdP group name and select an available Identity domain group name.
    2. If you select implicit grouping, you do not need to map an identity provider group name or identity domain group name.
  9. (Optional) Click Assign domain group memberships to assign group memberships from the identity domain.
    1. Click Add group.
    2. Select the groups that you want to add, and then click Add groups.
  10. Select one of the following from Assignment rules:
    • Merge with existing group memberships
    • Replace existing group memberships
  11. In the field When a group is not found....
    • Ignore the missing group: The user successfully signs in.
    • Fail the entire request: The sign in attempt fails.
  12. Click Save changes.
Export SAML Metadata
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Open an identity provider.
  4. Click Export SAML metadata.
  5. Select one of the following:
    • Metadata File: Select download the SAML XML metadata file, or download the SAML XML metadata with self-signed certificates.
    • Manual Export: Manually exporting the metadata allows you to choose from multiple SAML options, for example the Entity ID or Logout response URL. After you copy the export file, you can download the Service provider signing certificate or the Service provider encryption certificate.
    • Metadata URL: If your IdP supports downloading SAML metadata directly. Click Access signing certificate to allow clients to access the signing certificate without having to log into an IdP.
Adding a Social Identity Provider

You can add a social identity provider so that users can sign in to the identity domain with their social credentials. You can also allow users to self-register if they do not already have an account.

You can choose from any of the following predefined social login types:
  • Facebook

  • Google

  • LinkedIn

  • Microsoft

  • OpenID Connect

  • Twitter

  1. Create an application for the social identity provider; for example, go to the Google developer site to create a Google application.

  2. Configure the redirectUrl in the application created in Step 2. The redirectUrl must have the format: https://<Identity domain base URL>/oauth2/v1/social/callback.
    Note

    Ensure that the redirectUrl doesn't contain port number :443. If it does, update the existing URL to remove the port number or add a new URL without the port number to the identity provider application using the external provider developers' website.

    Each social identity provider calls these URLs by a different name. See the following list of the social identity providers and the names that they use for the URLs.
    • Facebook: Valid OAuth redirect URIs

    • Google and LinkedIn: Authorized redirect URL

    • Microsoft: Redirect URLs

    • Twitter: Callback URL

  3. Ensure that you retain the Client ID and the Client Secret from the application that you created at the social identity provider. You use this ID and Secret when configuring a social identity provider in the identity domain.

To add a social identity provider:

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Click Add IdP, and then click Add Social IdP.
  4. Click Type, and then choose a social login type.
  5. In the Name and Description fields, enter a name and description for the social identity provider.
    Note

    The social identity provider name can contain spaces. However, it can't contain special characters. Avoid entering confidential information.
  6. Enter the Client ID and the Client secret for the social login type.
  7. Set the Enable account linking option.
    • To allow users to link to their social accounts, select the check box to turn on this option.
    • To prevent users from linking to their social accounts, clear the check box to turn off this option.
      Note

      You can prevent users from linking to their social accounts for security or organizational purposes. For example, if a hacker accesses the user's social account, the hacker can't sign in to the identity domain to access resources and applications.
  8. When you are finished, click Add IdP.
  9. Locate the social identity provider that you created. Click the Actions menu (three dots), and then click Activate IdP to activate the social identity provider.
  10. Log in with the social identity provider.
    Note

    You might encounter this error: “Not Logged In: You are not logged in. Please log in and try again.”

    The most likely cause is that the application you created on the social identity provider side has the wrong Client ID or Redirect URL in the configuration. Check the Client ID and the Redirect URL configuration, and try to log in again.

Adding an X.509 Authenticated Identity Provider

Use an X.509 authenticated identity provider with certificate-based authentication to comply with FedRAMP requirements as well as Personal Identity Verification (PIV) cards. Adding an X.509 authenticated identity provider allows users to login using two-way SSL. Two-way SSL ensures that both the client and the server authenticate each other by sharing their public certificates and then verification is performed based on those certificates.

To add an X.509 authenticated identity provider:
  1. Navigate to the identity domain: Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Click Add IdP, and then click Add X.509 IdP.
  4. In the Name and Description fields, enter a name and description for the X.509 identity provider.
    Note

    The X.509 identity provider name can contain spaces. However, it can't contain special characters. Avoid entering confidential information.
  5. Click Import Certificate, and then provide a trusted partner certificate. This certificate is used to authenticate and encrypt the data for the trusted partner.
  6. (Optional) If you want to preserve the certificate file name, select the check box Keep the file name same as the original file.
  7. (Optional) If you want to identify the certificate keystore with an alias, click Alias, and then enter a name for the certificate. (Avoid entering confidential information.)
  8. When you are ready, click Import certificate.
  9. Choose a matching Certificate attribute type.
    • Default: Use the default filter to associate the identity domain user attributes to certificate attributes.
    • Simple filter: Use the simple filter to select an identity domain user attribute to associate it to a certificate attribute.
    • Advanced filter: Use the advanced filter to create a custom filter to associate the identity domain user attributes to certificate attributes. For example, you can use username eq “(assertion.subject.cn)” or emails.primary sw “(assertion.serialNumber)”.
  10. To validate certificates, select the Enable OSCP validation check box, and then do the following:
    • OSCP responder URL: Enter the OSCP responder URL.
    • Allow access if OSCP response is unknown: Select this check box to allow access for unknown certificates.
  11. When you are finished, click Add IdP.
Activating or Deactivating an Identity Provider

Deactivating an identity provider prevents users from being able to use the identity provider to access their Oracle Cloud services externally from a different login page than the one associated with their local Oracle Cloud account.

Activating an identity provider reinstates users to use the identity provider.

After you activate an identity provider, you can assign the identity provider to an identity provider policy. An identity provider policy allows you to define criteria to determine whether the identity provider appears for users on the Sign In page, either when they're accessing a specific app or attempting to access resources that are protected by the identity domain.

See Understand Identity Provider Policies for more information about identity provider policies, and Add an Identity Provider Policy to learn more about assigning identity providers to an identity provider policy.

Activating an Identity Provider
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. In the Identity providers page, click the Actions menu (three dots) for the identity provider that you want to activate.
  4. Click Activate IdP.
  5. To confirm the activation, click Activate IdP.
Deactivating an Identity Provider
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. In the list of Identity providers, click the Actions menu (three dots) for the identity provider that you want to deactivate.
  4. Click Deactivate IdP.
  5. To confirm the deactivation, click Deactivate IdP.
Assigning Identity Providers to the Policy

You can assign identity providers to an IdP policy. These identity providers will appear in the Sign In page, and a user can use them to access resources that are protected by IAM, such as the My Profile console or the IAM console.

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then IdP policies.
  3. Click the name of the IdP policy that you want to assign an IdP to.
  4. Under Resources, click Identity provider rules.
  5. Click the Actions menuAction menu (three dots) for the rule to which you want to assign an identity provider, then click Edit IdP rule.
  6. Click the Assign identity providers box and select the identity provider that you want to assign to this rule.
    Repeat this step to assign additional identity providers.
  7. When you are finished, click Save changes.
Testing an Identity Provider

After adding and activating an identity provider, you can test it. You can verify that you can use your federated SSO credentials to sign in to the identity domain through an external website.

  1. If you assigned the identity provider to an identity provider policy, then go to step 2. Otherwise, assign the identity provider to an identity provider policy. See Assign Identity Providers to the Policy.
  2. Sign out of the identity domain.
  3. In the Sign In page, verify that you see a link called <Identity_Provider_Name>.

    The <Identity_Provider_Name> placeholder represents the name you entered for the identity provider that you created.

    If, for example, you created an identity provider called Google, then the link appears as Google.

  4. Click the <Identity_Provider_Name> link.
  5. Sign in to the external website with your federated SSO credentials.
    The identity provider evaluates the user's sign-on credentials, verifies that the user is an authorized user, and returns this information to the identity domain.
    Tip

    If you no longer want to display the link to the identity provider in the Sign In page, then remove the identity provider from all identity provider policies and deactivate the identity provider. See Removing Identity Providers from the Policy and Deactivating an Identity Provider.
Updating an Identity Provider
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. Click the Actions menu (three dots) for the identity provider that you want to update.
  4. Select Edit IdP.
    A window that displays configuration settings for the IdP opens.
  5. Modify the configuration settings for the IdP.
  6. After editing the configuration settings for the IdP, click Save changes.
Deleting an Identity Provider
  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. Select the identity domain you want to work in and click Security and then Identity providers.
  3. If the identity provider that you want to delete is assigned to an identity provider policy, then remove it from the policy. See Remove Identity Providers from the Policy.
  4. In the list of Identity providers, click the Actions menu (three dots) for the identity provider that you want to delete.
  5. Click Delete IdP.
    Note

    Deleting a social identity provider removes the user profiles that are linked to that social identity provider. Alternatively, consider deactivating the social identity provider (which does not remove the user profiles) so that users can still see the accounts in My Profile but can't use them to sign in.
  6. To confirm the deletion, click Delete IdP.