Oracle Cloud Infrastructure Documentation

Federating with Microsoft Active Directory

This topic describes how to federate with Microsoft Active Directory using Microsoft Active Federation Services (AD FS).

Note

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

About Federating with Microsoft Active Directory

Your organization can have multiple Active Directory accounts (e.g., one for each division of the organization). You can federate multiple Active Directory accounts with Oracle Cloud Infrastructure, but each federation trust that you set up must be for a single Active Directory account.

To federate with Active Directory, you set up a trust between Active Directory and Oracle Cloud Infrastructure. To set up this trust, you perform some steps in the Oracle Cloud Infrastructure Console and some steps in Active Directory Federation Services.

Following is the general process an administrator goes through to set up federation with Active Directory. Details for each step are given in the sections below.

  1. Get required information from Active Directory Federation Services.
  2. Federate Active Directory with Oracle Cloud Infrastructure:

    1. Add the identity provider (AD FS) to your tenancy and provide the required information.
    2. Map Active Directory groups to IAM groups.
  3. In Active Directory Federation Services, add Oracle Cloud Infrastructure as a trusted, relying party.
  4. In Active Directory Federation Services, add the claim rules required in the authentication response by Oracle Cloud Infrastructure.
  5. Test your configuration by logging in to Oracle Cloud Infrastructure with your Active Directory credentials.

Federating with Active Directory

Prerequisites

You have installed and configured Microsoft Active Directory Federation Services for your organization.

You have set up groups in Active Directory to map to groups in Oracle Cloud Infrastructure.

Tip

Consider naming Active Directory groups that you intend to map to Oracle Cloud Infrastructure groups with a common prefix, to make it easy to apply a filter rule. For example, OCI_Administrators, OCI_NetworkAdmins, OCI_InstanceLaunchers.

Step 1: Get required information from Active Directory Federation Services

Summary: Get the SAML metadata document and the names of the Active Directory groups that you want to map to Oracle Cloud Infrastructure Identity and Access Management groups.

  1. Locate the SAML metadata document for your AD FS federation server. By default, it is located at this URL:

    https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml

    Download this document and make a note of where you save it. You will upload this document to the Console in the next step.

  2. Note all the Active Directory groups that you want to map to Oracle Cloud Infrastructure IAM groups. You will need to enter these in the Console in the next step.

Step 2: Add Active Directory 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 login 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 (e.g., ABCCorp_ADFS shown in the screenshot in Experience for Federated Users). 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 in Step 1.
    5. Click Show Advanced Options.
    6. Encrypt Assertion: Select the check box. Microsoft AD FS encrypts the assertion by default. Selecting the check box lets the IAM service know to expect the encryption from AD FS. For more information, see Encrypt Assertion.
    7. 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.
  6. Set up the mappings between Active Directory groups and IAM groups in Oracle Cloud Infrastructure. A given Active Directory group can be mapped to zero, one, or multiple IAM groups, and vice versa. However, each individual mapping is between only a single Active Directory 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

    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.

    To create a group mapping:

    1. Under Identity Provider Group, enter the Active Directory group name. You must enter the name exactly, including the correct case.

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

      Tip

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

    2. Repeat the above sub-steps for each mapping you want to create, and then click Create.

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 3: Copy the URL for the Oracle Cloud Infrastructure Federation Metadata document

Summary: The Federation page displays a link to the Oracle Cloud Infrastructure Federation Metadata document. Before you move on to configuring Active Directory Federation Services, you need to copy the URL.

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

  2. Copy the URL. The URL looks similar to:

    https://auth.r2.oracleiaas.com/v1/saml/ocid1.tenancy.oc1..aaaaaaaaqdt2tvdmhsa3jmvc5dzulgs3pcv6imfwfgdya4aq/metadata.xml

Step 4: In Active Directory Federation Services, add Oracle Cloud Infrastructure as a trusted relying party

  1. Go to the AD FS Management Console and sign in to the account you want to federate.
  2. Add Oracle Cloud Infrastructure as a trusted relying party:

    1. From the AD FS Management Console, right-click AD FS and select Add Relying Party Trust.

    2. In the Add Relying Party Trust Wizard, click Start.

    3. Select Import data about the relying party published online or on a local network.

      Paste the Oracle Cloud Infrastructure Federation Metadata URL that you copied in Step 3. Click Next.

      AD FS will connect to the URL. If you get an error during the attempt to read the federation metadata, you can alternatively upload the Oracle Cloud Infrastructure Federation Metadata XML document.

      To upload the federation metadata document
    4. Set the display name for the relying party (e.g., Oracle Cloud Infrastructure) and then click Next.

    5. Select I do not want to configure multi-factor authentication settings for this relying party trust at this time.
    6. Choose the appropriate Issuance Authorization Rules to either permit or deny all users access to the relying party. Note that if you choose "Deny", then you must later add the authorization rules to enable access for the appropriate users.

      Click Next.

    7. Review the settings and click Next.
    8. Check Open the Edit Claim Rules dialog for this relying part trust when the wizard closes and then click Close.

Step 5: Add the claim rules for the Oracle Cloud Infrastructure relying party

Summary: Add the claim rules so that the elements that Oracle Cloud Infrastructure requires (Name ID and groups) are added to the SAML authentication response.

Add the Name ID rule:

  1. In the Add Transform Claim Rule Wizard, select Transform an Incoming Claim, and click Next.
  2. Enter the following:

    • Claim rule name: Enter a name for this rule, e.g., nameid.
    • Incoming claim type: Select Windows account name.
    • Outgoing claim type: Select Name ID.
    • Outgoing name ID format: Select Persistent Identifier.
    • Select Pass through all claim value.
    • Click Finish.
  3. The rule is displayed in the rules list. Click Add Rule.

Add the groups rule:

Important

Any users who are in more than 100 IdP groups cannot be authenticated to use the Oracle Cloud InfrastructureConsole. To enable authentication, apply a filter to the groups rule, as described below.

If your Active Directory users are in no more than 100 groups
If your Active Directory users are in more than 100 groups

Step 6: 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 7: 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

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

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: