Federating with Microsoft Active Directory

Many companies use an identity provider to manage user logins and passwords and to authenticate users for access to secure websites, services, and resources. To access the Oracle Private Cloud Appliance Service Web UI, users must also sign in with a user name and password. An administrator can federate with a supported identity provider so that each user can use their existing login and password, rather than having to create new credentials to access and use cloud resources.

Federation involves setting up a trust relationship between the identity provider and Private Cloud Appliance. When an administrator has established this relationship, federated users are prompted with a single sign-on when accessing the Service Web UI.

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

You can federate multiple Active Directory (AD) accounts with Private Cloud Appliance (for example, one for each division of the organization), but each federation trust that you set up must be for a single AD account. To set up a trust, you perform some tasks in the Private Cloud Appliance Service Web UI and some tasks in Active Directory Federation Services (ADFS).

Before you begin federating, make sure you already have:

Installed and configured Microsoft Active Directory Federation Services for your organization.
Set up groups in Active Directory that will map to groups in Private Cloud Appliance.
Created users in Active Directory who will sign into the Private Cloud Appliance Service Web UI.

Note:

Consider naming Active Directory groups that you intend to map to Private Cloud Appliance groups with a common prefix to make it easy to apply a filter rule, for example, PCA_Administrators, PCA_NetworkAdmins, PCA_InstanceLaunchers.

Gathering Required Information from ADFS

To federate with Oracle Private Cloud Appliance you need to have the SAML metadata document and the names of the Active Directory (AD) groups that you want to map to Private Cloud Appliance groups.

Locate and download the SAML metadata document for your ADFS, which is by default at:
```
https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
```
This is the document you will upload when you create the identity provider.
Make a note of all the AD groups that you want to map to Private Cloud Appliance groups.

Caution:

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

Caution:

You can skip this section if your ADFS certificate is signed by a known certificate authority because they should already exist in the Private Cloud Appliance certificate bundle.

The Oracle Private Cloud Appliance Certificate Authority (CA), is self-signed OpenSSL generated root and intermediate x.509 certificate. These CA certificates are used to issue x.509 server/client certificates allowing you to add outside Certificate Authority (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, you will 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 on how to find the web server's certificate chain and then follow steps 3-8.

To add outside CA trust information, complete the following steps:

From a browser, enter the following URL and download the SAML metadata document for your ADFS, which is by default at:
```
https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
```

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>

Log on to management node 1 whose default name is pcamn01.
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.
In the customer_ca directory, create a new file in PEM format.
Copy the certificate from the FederationMetadata.xml file, which is located within the <X509Certificate> tag, and paste into the new PEM file. Be sure to include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, for example:
```
-----BEGIN CERTIFICATE-----
<CERTIFICATE CONTENT>
-----END CERTIFICATE-----
```
Save the file and close.

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

To federate with an identity provider in Oracle Private Cloud Appliance you create it in either the Service Web UI or the Service CLI and map account groups.

After you create your identity provider, you might have the need to make an update. For example, you will need to update your metadata XML file when it expires. You can also view all identity providers, view details of or delete an identity provider.

Adding Active Directory as an Identity Provider

To federate with Active Directory (AD) in Oracle Private Cloud Appliance you must add it as an identity provider. At the same time, you can set up the group mappings or you can set them up later.

To add AD as an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

Sign in with your Private Cloud Appliance login and password.
Open the navigation menu and click Identity Provider.
On the Identity Providers page, click Create Identity Provider.
On the Create an Identity Provider page, provide the following information:
1. Display Name
  
  The name that the federated users see when choosing which identity provider to use for signing in to the Service Web UI. This name must be unique across all identity providers 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 a 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 URL
  
  Enter the URL for the FederationMetadata.xml document from the identity provider.
  
  By default, the metadata file for ADFS is located at
```
https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
```
Click Create Identity Provider.

Your new identity provider is assigned an OCID and is displayed on the Identity Providers page

After the identity provider is added, you must set up the group mappings between Private Cloud Appliance and Active Directory.

To set up group mappings, see Creating Group Mappings.

Updating an Identity Provider

To update an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

Open the navigation menu and click Identity Providers.

A list of the identity providers is displayed.
For the identity provider you want to update, click the Actions icon (three dots) and then click Edit.
Change any of the following information; however, be aware that changing this information can affect the federation:
1. Description
2. Authentication Contexts
  
  Add or delete a class reference.
3. Encrypt Assertion
  
  Enable or disable encrypted assertions from the identity provider.
4. Force Authentication
  
  Enable or disable redirect authentication from the identity provider.
5. Metadata URL
  
  Enter the URL for a new FederationMetadata.xml document from the identity provider.
For more information, see step 4 in Adding Active Directory as an Identity Provider.
Click Update Identity Provider.

Viewing Identity Provider Details

The identity provider details page displays general information such as authentication contexts. It also provides the identity provider's settings, which include the redirect URL.

From this page, you can also edit the identity provider and manage the group mappings.

To view details for an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

Open the navigation menu and click Identity Providers.

A list of the identity providers is displayed.
For the identity provider whose details you want to view, click the Actions icon (three dots) and then click View Details.

The identity provider details page is displayed.

Listing Identity Providers

To list the identity providers, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

Open the navigation menu and click Identity Providers.

A list of the identity providers is displayed.

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, which also deletes all of the associated group mappings.

To delete an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

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

A list of the identity providers is displayed.
For the identity provider you want to delete, click the Actions icon (three dots) and then click Delete.
At the Delete Identity Provider prompt, click Confirm.

Working with Group Mappings for an Identity Provider

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

A given Active Directory group is mapped to a single Oracle 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 can't update a group mapping, but 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.

To create a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each identity provider group you want to map.

Using the Service Web UI

Open the navigation menu and click IDP Group Mappings.

A list of the identity provider group mappings is displayed.
Click Create Group Mapping.

The IDP Group Mapping Form is displayed
In the Name field, enter a name for the IDP group mapping.
In the IDP Group Name field, enter the exact name of the identity provider group.
From the Admin Group Name list, select the Private Cloud Appliance group you want to map to the identity provider group.
Optionally, enter a Description of the group.
Click Create IDP Group Mapping.

The new group mapping is displayed in the list.

Updating a Group Mapping

To update a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each group mapping you want to map.

Using the Service Web UI

Open the navigation menu and click IDP Group Mappings.

A list of the identity provider group mappings is displayed.
For the group mapping you want to update, click the Actions icon (three dots) and then click Edit.

The IDP Group Mapping Form is displayed.
Modify any of the following fields; however, be aware that changing this information can affect the federation:
1. Name
2. IDP Group Name
3. Admin Group Name
4. Description
Click Modify IDP Group Mapping.

The updated group mapping is displayed in the list.

Viewing Group Mappings

To view group mapping details, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

Open the navigation menu and click IDP Group Mappings.

A list of the identity provider group mappings is displayed.

Deleting a Group Mapping

To delete a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each identity provider group you want to delete.

Using the Service Web UI

Open the navigation menu and click IDP Group Mappings.

A list of the identity provider group mappings is displayed.
For the group mapping you want to delete, click the Actions icon (three dots) and then click Delete.
At the Deleting IDP Group Mapping prompt, click Confirm.

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

Add Relying Party in ADFS

In the Service Web UI on the Identity Providers 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
Click "Click Here".

A metadata XML file opens in the browser with a URL similar to:
```
https://adminconsole.system-name.domain-name/wsapi/rest/saml/metadata/
```
Copy the metadata XML file URL.
From the system installed with ADFS, open a browser window and paste the URL.
Save the file, making sure to use the .xml extension, for example, my-sp-metadata.xml.
Go to the AD FS Management Console and sign in to the account you want to federate.
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 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:

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

The Select Rule Template dialog is displayed.
For Claim rule template, select Transform an Incoming Claim and then click Next.
Enter the following:
- Claim rule name: Enter a name for this rule, for example, nameid.
- Incoming claim type: Select 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 Active Directory users are in no more than 100 groups, you simply add the groups rule. However, if your Active Directory users are in more than 100 groups, those users cannot be authenticated to use the Private Cloud Appliance Service Web UI. For these groups, you must apply a filter to the groups rule.

To add the groups rule:

In the Issuance Transform Rules dialog, click Add Rule.

The Select Rule Template dialog is displayed.
For Claim rule template, select Send Claims Using a Custom Rule and then click Next.

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

Claim rule name: Enter groups.

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);

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.

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

Providing Federated Users Sign In Information

Before federated users can log in to the Private Cloud Appliance Service Web UI, you must provide them with the URL. You must also ensure that you have configured the groups mappings otherwise a federated user cannot do any work in Private Cloud Appliance.