Oracle Cloud Infrastructure Documentation

Federating with Microsoft Azure Active Directory

This topic describes how to federate with Microsoft Azure Active Directory (AD).

Note

Before following the steps in this topic, see Federating with Identity Providers to ensure that you understand general federation concepts.

About Federating with Azure AD

To federate with Azure AD, you set up Oracle Cloud Infrastructure as a basic SAML single sign-on application in Azure AD. To set up this application, you perform some steps in the Oracle Cloud Infrastructure Console and some steps in Azure AD.

Following is the general process an administrator goes through to set up the federation. Details for each step are given in the next section.

  1. In Oracle Cloud Infrastructure, download the federation metadata document.
  2. In Azure AD, set up Oracle Cloud Infrastructure Console as an enterprise application.

  3. In Azure AD, configure the Oracle Cloud Infrastructure enterprise application for single sign-on.
  4. In Azure AD, set up the user attributes and claims.
  5. In Azure AD, download the Azure AD SAML metadata document.
  6. In Azure AD, assign user groups to the application.
  7. In Oracle Cloud Infrastructure, set up Azure AD as an identity provider.
  8. In Oracle Cloud Infrastructure, map your Azure AD groups to Oracle Cloud Infrastructure groups.
  9. In Oracle Cloud Infrastructure, set up the IAM policies to govern access for your Azure AD groups.
  10. Share the Oracle Cloud Infrastructure sign-in URL with your users.

Steps to Federate with Azure AD

Prerequisites

You have an Azure tenancy with groups and users set up in Azure AD.

Step 1: In Oracle Cloud Infrastructure, download the federation metadata document

Summary: The Oracle Cloud Infrastructure Console Federation page displays a link to the Oracle Cloud Infrastructure federation metadata document. Before you set up the application in Azure AD, you need to download the document.

  1. Go to the Federation page: Open the navigation menu. Under Governance and Administration, go to Identity and click Federation.

  2. On the Federation page, click Download this document.

    Download link on Console Federation page

    After you click the link, the metadata.xml document opens in your browser window. Use your browser's Save page as command to save the xml document locally where you can access it later.

Step 2: In Azure AD, add Oracle Cloud Infrastructure as an enterprise application

  1. In the Azure portal, on the left navigation panel, select Azure Active Directory.

  2. In the Azure Active Directory pane, select Enterprise applications. A sample of the applications in your Azure AD tenant is displayed.

  3. At the top of the All applications pane, click New application.
  4. In the Add from gallery region, enter Oracle Cloud Infrastructure Console in the search box.
  5. Select the Oracle Cloud Infrastructure Console application from the results and select Add.

  6. In the application-specific form, you can edit information about the application. For example, you can edit the name of the application.

  7. When you are finished editing the properties, select Add.

    The getting started page is displayed with the options for configuring the application for your organization.

Step 3: In Azure AD, configure Oracle Cloud Infrastructure as an enterprise application

  1. Under the Manage section, select Single sign-on.

    Azure AD Single sign-on option
  2. Select SAML to configure single sign-on. The Set up Single Sign-On with SAML - Preview page is displayed.

  3. At the top of the page, click Upload metadata file.

    Azure AD upload metadata link
  4. Locate the federation metadata file (metadata.xml) you downloaded from Oracle Cloud Infrastructure in Step 1, and upload it here. After you upload the file, these Basic SAML Configuration fields are automatically populated:

    • Identifier (Entity ID)
    • Reply URL (Assertion Consumer Service URL)
  5. In the Basic SAML Configuration section, click Edit. On the Basic SAML Configuration pane, enter the following required field:

    • Sign on URL: Enter the URL in the following format:

      https://console.<oci_home_region>.oraclecloud.com

      where oci_home_region is your tenancy's home region. For example, if you home region is Ashburn, enter:

      https://console.us-ashburn-1.oraclecloud.com

       How do I find my tenancy home region?

      Azure AD Basic SAML Configuration panel
  6. Click Save.

Step 4. Configure User Attributes & Claims

The Oracle Cloud Infrastructure Console enterprise application template is seeded with the required attributes, so you don't need to add any. However, you do need to make the following customizations:

  1. In the User Attributes & Claims section, click Edit in the upper-right corner. The Manage user claims panel is displayed.
  2. Next to the Name identifier value field, click Edit.

    • Under Choose name identifier format, select Persistent.
    • For Source, select Attribute.
    • For Source attribute, select user.userprincipalname.

      Azure AD Manage User Claims panel
    • Click Save.

  3. Next to the Groups returned in claim field, click Edit.
  4. In the Group Claims (Preview) panel, configure the following:

    • Select Security groups.
    • Source attribute: Select Group ID.
    • Under Advanced Options, select Customize the name of the group claim.
    • In the Name field, enter: groupName.

      Ensure that you enter groupName with spelling and case exactly as given.

    • In the Namespace field, enter: https://auth.oraclecloud.com/saml/claims

      Azure AD Group Claims panel
    • Click Save.

Step 5: Download the SAML metadata document

  1. On the SAML Signing Certificate section, click the download link next to Federation Metadata XML.

    Azure AD download federation metadata xml link
  2. Download this document and make a note of where you save it. You will upload this document to the Console in the next step.

Step 6. Assign user groups to the application

To enable Azure AD users to sign in to Oracle Cloud Infrastructure, you need to assign the appropriate user groups to your new enterprise application.

  1. On the left navigation pane, under Manage, select Users and Groups.
  2. Click Add at the top of the Users and Groups list to open the Add Assignment pane.
  3. Click the Users and groups selector.

  4. Enter the name of the group you want to assign to the application into the Search by name or email address search box.

  5. Hover over the group in the results list to display a check box. Select the check box to add the group to the Selected list.

  6. When you are finished selecting groups, click Select to add them to the list of users and groups to be assigned to the application.

  7. Click Assign to assign the application to the selected groups.

Step 7: Add Azure AD as an identity provider in Oracle Cloud Infrastructure

Summary: Add the identity provider to your tenancy. You can set up the group mappings at the same time, or set them up later.

  1. Go to the Console and sign in with your Oracle Cloud Infrastructure username and password.
  2. Open the navigation menu. Under Governance and Administration, go to Identity and click Federation.
  3. Click Add identity provider.
  4. Enter the following:

    1. Display Name: A unique name for this federation trust. This is the name federated users see when choosing which identity provider to use when signing in to the Console. The name must be unique across all identity providers you add to the tenancy. You cannot change this later.
    2. Description: A friendly description.
    3. Type: Select Microsoft Active Directory Federation Services (ADFS) or SAML 2.0 compliant identity provider.
    4. XML: Upload the FederationMetadata.xml file you downloaded from Azure AD.
    5. Click Show Advanced Options.
    6. Encrypt Assertion: Selecting the check box lets the IAM service know to expect the encryption from IdP. Do not select this check box unless you have enabled assertion encryption in Azure AD.

      To enable assertion encryption for this single sign-on application in Azure AD, set up the SAML Signing Certificate in Azure AD to sign the SAML response and assertion. For more information, see the Azure AD documentation.

    7. Force Authentication: Selected by default. When selected, users are required to provide their credentials to the IdP (re-authenticate) even when they are already signed in to another session.
    8. Authentication Context Class References: This field is required for Government Cloud customers. When one or more values are specified, Oracle Cloud Infrastructure (the relying party), expects the identity provider to use one of the specified authentication mechanisms when authenticating the user. The returned SAML response from the IdP must contain an authentication statement with that authentication context class reference. If the SAML response authentication context does not match what is specified here, the Oracle Cloud Infrastructure auth service rejects the SAML response with a 400.

      Several common authentication context class references are listed in the menu. To use a different context class, select Custom, then manually enter the class reference.

    9. Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.

  5. Click Continue.

    Note

    If you don't want to set up the group mappings now, you can simply click Create and come back to add the mappings later.

Step 8. Add group mappings

Summary: Set up the mappings between Azure AD groups and IAM groups in Oracle Cloud Infrastructure. A given Azure AD group can be mapped to zero, one, or multiple IAM groups, and vice versa. However, each individual mapping is between only a single Azure AD group and a single IAM group. Changes to group mappings take effect typically within seconds in your home region, but may take several minutes to propagate to all regions. Note that the Azure AD groups that you choose to map must also be assigned to the enterprise application in Azure AD. See Step 6. Assign user groups to the application.

Before you begin: Have your Azure AD groups page open. From the Azure Dashboard, under Manage, select Groups. From the list of groups, select the group you want to map to an Oracle Cloud Infrastructure group. In the group's details page, click the Copy icon next to the Object ID for the group.

To create a group mapping:

  1. For Identity Provider Group, select Custom Group. Enter (or paste) the Object ID of the Azure AD group. You must enter the Object ID exactly, including the correct case. An example Object ID looks like: aa0e7d64-5b2c-623g-at32-65058526179c

    Mapping an Azure AD group to an OCI group
  2. Choose the IAM group you want to map from the list under OCI Group. If you instead want to create a new IAM group, select New OCI Group and enter the name of the new group in New OCI Group Name. The new group is automatically created in IAM and mapped to the IdP group. It will also automatically be given this description, which you can't change: "Group created during federation".

  3. Repeat the preceding steps for each mapping you want to create, and then click Create.

Tip

Requirements for IAM group name: No spaces. Allowed characters: letters, numerals, hyphens, periods, underscores, and plus signs (+). The name cannot be changed later.

The identity provider is now added to your tenancy and appears in the list on the Federation page. Click the identity provider to view its details and the group mappings you just set up.

Oracle assigns the identity provider and each group mapping a unique ID called an Oracle Cloud ID (OCID). For more information, see Resource Identifiers.

In the future, come to the Federation page if you want to edit the group mappings or delete the identity provider from your tenancy.

Step 9: Set up IAM policies for the groups

If you haven't already, set up IAM policies to control the access the federated users have to your organization's Oracle Cloud Infrastructure resources. For more information, see Getting Started with Policies and Common Policies.

Step 10: Give your federated users the name of the tenant and URL to sign in

The federated users need the URL for the Oracle Cloud Infrastructure Console (for example, https://console.us-ashburn-1.oraclecloud.com) and the name of your tenant. They'll be prompted to provide the tenant name when they sign in to the Console.

Managing Identity Providers in the Console

To delete an identity provider
To add group mappings for an identity provider
To update a group mapping
To delete a group mapping

Managing Identity Providers in the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations:

Identity providers:

Group mappings: