1. User Guide
  2. Identity and Access Management
  3. Federating with Microsoft Active Directory

Federating with Microsoft Active Directory

Federating enables users at your company to use the same login credentials for the Private Cloud Appliance Compute Web UI that they already use for other logins in the company. To federate, an administrator creates a trust relationship between the existing identity provider and Oracle Private Cloud Appliance. When this relationship is established, federated users are prompted with a single sign-on when accessing the Compute Web UI.

For more information, see "Federating with Identity Providers" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

You can federate multiple Active Directory (AD) accounts with Oracle Private Cloud Appliance. Each federation trust is for a single AD account. To create a trust, you perform some tasks in the Oracle Private Cloud Appliance Compute Web UI and some tasks in Active Directory Federation Services (ADFS).

Before you begin federating, make sure you have completed the following tasks:

  • Installed and configured Microsoft ADFS for your organization.

  • Created groups in AD that will map to groups in Oracle Private Cloud Appliance.

  • Created users in AD who will sign into the Oracle Private Cloud Appliance Compute Web UI.

Note:

Consider using a common prefix to name AD groups that you intend to map to Oracle Private Cloud Appliance. For example, use AD group names such as PCA_Administrators, PCA_NetworkAdmins, PCA_InstanceLaunchers.

Gathering Required Information from ADFS

To federate with Private Cloud Appliance, you need to have the SAML metadata document and the names of the AD groups that you want to map to Private Cloud Appliance groups.

  1. Locate and download the SAML metadata document for your ADFS. The default location is:

    https://your_hostname/FederationMetadata/2007-06/FederationMetadata.xml

    You will upload this document when you create the identity provider.

  2. Make a note of all the AD groups that you want to map to Private Cloud Appliance groups.

    Important:

    Ensure that you have all the Private Cloud Appliance groups configured before you add AD as an identity provider.

Verifying Identity Provider Self-Signed Certificates

Important:

You can skip this verification step if your ADFS certificate is signed by a known certificate authority. ADFS certificates that are signed by a known certificate authority should already exist in the Private Cloud Appliance certificate bundle.

The Private Cloud Appliance Certificate Authority (CA) is a self-signed OpenSSL generated root and intermediate x.509 certificate. This CA certificate is used to issue x.509 server/client certificates, enabling you to add outside CA trust information to the rack. If you use a self-signed certificate for ADFS, you will need to add outside CA trust information from ADFS to the management nodes on the rack.

Note:

If you are using the metadataUrl property to create or update an identity provider, then you need to add the identity provider's web server's certificate chain to the Private Cloud Appliance outside CA bundle. See your identity provider's documentation for how to find the web server's certificate chain and then perform Steps 3-8 in the following procedure.

Adding Outside CA Trust Information

  1. From a browser, download the SAML metadata document for your ADFS as described in Gathering Required Information from ADFS

  2. Open the file in a text or XML editor and locate the signing certificate section. For example:

    <KeyDescriptor use="signing">
<KeyInfo>
<X509Data>
<X509Certificate>
<!--CERTIFICATE IS HERE-->
</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>

  3. Log on to management node 1. By default, the name of management node 1 is pcamn01.

  4. Navigate to /etc/pca3.0/vault and create a new directory named customer_ca.

    Note:

    You can use this directory for multiple files. For example, you can create a file for the identity provider certificate and one for the web server's certificate chain.

  5. In the customer_ca directory, create a new file with extension .pem.

  6. Copy the certificate from the FederationMetadata.xml file, which is located between the <X509Certificate> and </X509Certificate> tag set, and paste the certificate into the new .pem file. Be sure to include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. For example: 

    -----BEGIN CERTIFICATE-----
CERTIFICATE CONTENT
-----END CERTIFICATE-----

  7. Save and close the file.

  8. Run the following command to update the ca_outside_bundle.crt on all management nodes: 

    python3 /usr/lib/python3.6/site-packages/pca_foundation/secret_service/cert_generator/cert_generator_app.py -copy_to_mns

Managing Identity Providers

This section also describes how to update your identity provider (for example, to update your metadata XML file when it expires), and how to view all identity providers, view details of an identity provider, and delete an identity provider.

Adding Active Directory as an Identity Provider

To federate with AD in Private Cloud Appliance, add AD as an identity provider. You can map account groups when you add AD as an identity provider, or you can map the account groups later.

Important:

Ensure that you have all the Private Cloud Appliance groups configured before you add AD as an identity provider.

Using the Compute Web UI

  1. Sign in with your Private Cloud Appliance login and password.

  2. Open the navigation menu, click Identity, and then click Federation.

  3. On the Federation page, click the Create Identity Provider button.

  4. On the Create Identity Provider dialog, provide the following information:

    1. Display Name

      The name that the federated users see when they choose which identity provider to use to sign in to the Compute Web UI. This name must be unique across all identity providers that you add to the tenancy and cannot be changed.

    2. Description

      A friendly description of the identity provider.

    3. Authentication Contexts

      Click Add Class Reference and select an authentication context from the list.

      When one or more values are specified, Private Cloud Appliance (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 identity provider 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 Private Cloud Appliance authentication service rejects the SAML response with response code 400.

    4. Encrypt Assertion (Optional)

      When enabled, the authorization service expects encrypted assertions from the identity provider. Only the authorization service can decrypt the assertion. When not enabled, the authorization service expects SAML tokens to be unencrypted, but protected, by SSL.

    5. Force Authentication (Optional)

      When enabled, users are always asked to authenticate at their identity provider when redirected by the authorization service. When not enabled, users are not asked to re-authenticate if they already have an active login session with the identity provider.

    6. Metadata

      Upload the FederationMetadata.xml document from your SAML 2.0 compliant identity provider. You can drag and drop the file or you can paste the XML content.

    7. Tagging (Optional)

      Add any free-form or defined tags as described in Adding Tags at Resource Creation. Tags can also be applied later.

  5. Click the Create Identity Provider button.

    Your new identity provider is assigned an OCID and is displayed on the Federations page.

After the identity provider is added to your tenancy, create the group mappings between Private Cloud Appliance and Active Directory, as described in Creating Group Mappings.

Listing Identity Providers

Use this procedure to list all identity providers for a tenancy.

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The Federation page opens with a list of all identity providers that are configured in this tenancy.

Using the OCI CLI

  1. Get the following information:

    • The OCID of the tenancy (oci iam compartment list -include-root)

    • The protocol used for federation (SAML2)

  2. Run the identity provider list command.

    $ oci iam identity-provider list -c ocid1.tenancy.unique_ID \
--protocol SAML2

Viewing Identity Provider Details

Use this procedure to show detailed information for a specific identity provider.

The details shown for the identity provider include the OCID, authentication contexts, and settings such as the redirect URL.

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. For the identity provider whose details you want to view, click the Actions menu, and then click View Details.

    The details page for that identity provider is displayed.

Using the OCI CLI

  1. Get the OCID of the identity provider (oci iam identity-provider list)

  2. Run the identity provider get command.

    $ oci iam identity-provider get --identity-provider-id ocid1.identityprovider.unique_ID

Updating an Identity Provider

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. For the identity provider that you want to update, click the Actions menu, and then click Edit.

  3. You can change any of the following information. For more complete descriptions, see Step 4 in Adding Active Directory as an Identity Provider. Consider the affect that some of these changes have on the federation.

    • Description

    • Authentication Contexts

      Add or delete a class reference.

    • Encrypt Assertion

      Enable or disable encrypted assertions from the identity provider.

    • Force Authentication

      Enable or disable redirect authentication from the identity provider.

    • Metadata

      Upload a new FederationMetadata.xml document from the identity provider.

    • Tagging

      Add or delete any free-form or defined tags.

  4. Click the Update Identity Provider button.

Deleting an Identity Provider

If you want to remove the option for federated users to log into Private Cloud Appliance, you must delete the identity provider. Deleting the identity provider also deletes all of the associated group mappings.

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. For the identity provider that you want to delete, click the Actions menu and then click Delete.

  3. At the Delete Identity Provider prompt, click Confirm.

    A Success pop-up displays briefly, and then the identity provider is no longer in the Federation list.

Working with Group Mappings for an Identity Provider

When working with group mappings, keep in mind the following:

  • A given AD group is mapped to a single Private Cloud Appliance group.

  • Private Cloud Appliance group names cannot contain spaces and cannot be changed later. Allowed characters are letters, numerals, hyphens, periods, underscores, and plus signs (+).

  • You cannot update a group mapping. You can delete the mapping and add a new one.

Creating Group Mappings

After you have created an identity provider, you must create mappings from ADFS groups to Private Cloud Appliance groups.

Repeat the following procedure for each identity provider group you want to map.

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. Click the identity provider for which you want to create group mappings.

    The details page for that identity provider is displayed.

  3. Scroll to the Resources section and click Group Mappings.

    The group mappings for this identity provider are listed.

  4. Click the Add Mappings button.

    The Create IDP Group Mapping dialog is displayed.

  5. In the Name field, enter the exact name of the identity provider group.

  6. From the Group list, select the Private Cloud Appliance group you want to map to the identity provider group.

  7. Click Create IDP Group Mapping.

    The new group mapping is displayed in the list.

Viewing Group Mappings

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. Click the name of the identity provider.

    The details page for that identity provider is displayed.

  3. Scroll to the Resources section and click Group Mappings.

    The group mappings for this identity provider are listed.

Deleting a Group Mapping

Repeat the following procedure for each identity provider group you want to delete.

Using the Compute Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    The identity providers that are configured in this tenancy are listed.

  2. Click the identity provider for which you want to delete a group mapping.

    The details page for that identity provider is displayed.

  3. Scroll to the Resources section and click Group Mappings.

    The group mappings for this identity provider are listed.

  4. For the group mapping that you want to delete, click the Actions menu and then click Delete.

  5. Click Confirm when prompted.

    A Success pop-up displays briefly, and then the identity provider group mapping is no longer in the Group Mappings list.

Adding Oracle Private Cloud Appliance as a Trusted Relying Party in ADFS

To complete the federation process, you must add Private Cloud Appliance as a trusted relying party in ADFS and then add associated relying party claim rules.

  1. In the Compute Web UI on the Federation page, view the following text block:

    You need the Private Cloud Appliance Federation Metadata document when setting up a trust with Microsoft Active Directory Federation Services or with other SAML 2.0-compliant identity providers. This is an XML document that describes the Private Cloud Appliance endpoint and certificate information. Click Here

  2. Click "Click Here."

    A metadata XML file opens in the browser with a URL similar to:

    https://console.system-name.domain-name/wsapi/rest/saml/metadata/ocid1.tenancy.unique_ID

  3. Copy the metadata XML file URL.

  4. From the system installed with ADFS, open a browser window and paste the URL.

  5. Save the file, making sure to use the .xml extension. For example, my-sp-metadata.xml.

  6. Go to the AD FS Management Console and sign in to the account you want to federate.

  7. Add Private Cloud Appliance as a trusted relying party.

    1. Under AD FS, right-click Relying Party Trusts and the select Add Relying Party Trust.

    2. In the Add Relying Party Trust Wizard Welcome page, select Claims Aware and then click Start.

    3. On the Select Data Source page, select "Import data about the relying party from a file."

    4. Click Browse and navigate to your my-sp-metadata.xml file and then click Open.

    5. On the Specify Display Name page, enter a display name, add any optional notes for the relying party, and then click Next.

    6. On the Choose Access Control Policy page, select the type of access you want to grant and then click Next.

    7. On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.

    8. On the Finish page, check "Configure claims issuance policy for this application" and then click Close.

      The Edit Claim Issuance Policy dialog appears, which you can leave open for the next section.

Adding Relying Party Claim Rules

After you add Private Cloud Appliance as a trusted relying party, you must add the claim rules so that the elements required (Name ID and groups) are added to the SAML authentication response.

To add a Name ID rule:

  1. In the Edit Claim Issuance Policy dialog, click Add Rule.

    The Select Rule Template dialog is displayed.

  2. For Claim rule template, select Transform an Incoming Claim and then click Next.

  3. Enter the following:

    • Claim rule name: Enter a name for this rule. For example, nameid.

    • Incoming claim type: Select the Microsoft Windows account name.

    • Outgoing claim type: Select a claim type, for example, Name ID.

    • Outgoing name ID format: Select Persistent Identifier.

    • Select Pass through all claim values and then click Finish.

      The rule is displayed in the rules list.

The Issuance Transform Rules dialog displays the new rule.

If your AD users are in no more than 100 groups, you simply add the groups rule. However, if your AD users are in more than 100 groups, those users cannot be authenticated to use the Private Cloud Appliance Compute Web UI. For these groups, you must apply a filter to the groups rule.

To add the groups rule:

  1. In the Issuance Transform Rules dialog, click Add Rule.

    The Select Rule Template dialog is displayed.

  2. For Claim rule template, select Send Claims Using a Custom Rule and then click Next.

  3. In the Add Transform Claim Rule Wizard, enter the following:

    1. Claim rule name: Enter groups.

    2. Custom rule: Enter the custom rule. 

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("https://auth.oraclecloud.com/saml/claims/groupName"), query = ";tokenGroups;{0}", param = c.Value);

    3. Click Finish.

The Issuance Transform Rules dialog displays the new rule.

Disable the Certificate Revocation Check

For ADFS to work with SAML, you must disable the Certificate Revocation List (CRL) checking.

  1. Open Powershell on the ADFS system and enter the following command, where TRUST_NAME is the name of the relying party trust:
    Get-AdfsRelyingPartyTrust -Name '<TRUST_NAME>' | Set-AdfsRelyingPartyTrust -EncryptionCertificateRevocationCheck None -SigningCertificateRevocationCheck None

Setting Up Policies for the Groups

Configure policies to control the access the federated users have to the Private Cloud Appliance resources. For general information about policies, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide. For specific information, see Managing Policies.

Providing Federated Users Sign-in Information

Do the following to enable a federated user to log into the Private Cloud Appliance Compute Web UI:

  • Provide the user with the URL for the Compute Web UI.

  • Provide the user with the name of the tenancy to which they have access.

  • Ensure that you have configured the necessary group mappings.

  • Ensure that you have configured the necessary policies.

Important:

A federated user cannot log into Private Cloud Appliance by using the OCI CLI.