Enabling the Federation Trust Relationship

Gathering Required ADFS Metadata

Identity federation requires the following information from the identity provider:

• The SAML metadata document from Active Directory Federation Services (ADFS)

  Its default location is: https://<id-provider-name>/FederationMetadata/2007-06/FederationMetadata.xml.

• The names of the Active Directory (AD) groups that you want to map to Private Cloud Appliance groups

  Make a note of all the AD groups that need mapping.

  Caution
  
  

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

Verifying Identity Provider Certificates

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

To add outside CA trust information, proceed as follows:

1. Download the SAML metadata document for your ADFS, which is available by default at:

   https://<id-provider-name>/FederationMetadata/2007-06/FederationMetadata.xml

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 (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 certificate chain.

5. In the customer_ca directory, create a new file in PEM format.

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

7. Save the file and close.

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

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

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 Microsoft Active Directory Federation Services (ADFS) and then add associated relying party claim rules.

Adding a Relying Party in ADFS

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

2. 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/

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

Adding Relying Party Claim Rules

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

To add a Name ID rule, proceed as follows:

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 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 Service Web UI. For these groups, you must apply a filter to the groups rule.

To add the groups rule, proceed as follows:

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:

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

Disabling 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