1. Using Oracle Mobile Cloud Service
  2. Reference
  3. Identity Provider Integration

G Identity Provider Integration

Here are the steps you need to follow to integrate various third-party identity providers with MCS.

Use Case: Configuring OKTA to Obtain a SAML Token

Here are the required fields that you must fill in if you’re configuring a SAML 2.0 app from OKTA.

Assuming that you have a user role with administrator privileges in OKTA:
  1. Log in to OKTA.
  2. Click Admin.
  3. Go to the Directory tab and specify the users to have access privileges to the application:

    • Select People to specify individual users

    • Select Group to specify a group of users

      By setting a group, you can later map a group of individuals to specific MCS roles by setting Role Attribute rules in the Keys and Certificates dialog. See Rule Types.

    • Select Directory Integration, then Add Active Directory to include all the users in the directory server

      or, alternatively, select LDAP to include all the users in an LDAP directory server
  4. Go to the Applications tab and click Add Application to create a new SAML 2.0 application.
  5. On the General Settings page, configure the SAML application.
    You’ll see several fields to fill in. For the token to be viable with MCS, you must fill-in the following fields:

    • Single Sign-On URL. This is the redirect URL where the response from the third-party IdP is sent. For example:

      https://hostname:####/saml

    • Audience URI. This is the intended audience of the SAML assertion. Set this value to the MCS SSO token endpoint URL.

      To exchange an externally-issued SAML token for an MCS-issued token that can be used with subsequent MCS API calls, ensure that the audience value specified in the token includes the MCS token exchange URL. The URL must include a port number, even when a default port is being used. For example:

      https://hostname:443/mobile/platform/sso/token

      You construct this endpoint by appending /mobile/platform/sso/exchange-token to your instance’s base URL. You can determine the base URL by opening any mobile backend in MCS, clicking its Settings tab, and looking in the Environment URLs section. For example: 

      https://hostname:443/mobile/platform/sso/exchange-token

    • Group Statement. This is where you can add additional group attributes to the token. In this field, you can filter which groups to add. There are different types of filtering options that you can choose from. For instance, if you used a naming convention for your group names, you can set an option (Regex or Start with) to filter groups that begin with a specific prefix.

      For example, say you defined several group of users, two groups for FixItFast employees, FIF-group1 and FIF-group2, and a group for RepairItFast employees, RIF-group1. If you enter FIF* as a value, only the users in the FixItFast group are added to the token.

  6. Once you’ve configured the app, go to the Single Sign-On page.
    This is where you’ll get the token issuer name that you’ll enter into the Token Issuer panel of token issuer. See Adding a Token Issuer.

    You’ll also want to get token certificate contents from this page. Paste the certificate contents in the Web Service and Token Certificates panel of the Keys and Certificates dialog when you add a token certificate. See Configuring a Web Service or Token Certificate.

Use Case: Configuring AD FS to Obtain a SAML Token

Configuring Active Directory Federation Services (AD FS) to obtain a SAML token involves providing similar information as you would for configuring another identity provider to obtain the token. You’ll configure an audience, provide a redirect URL to obtain the token, and configure some rules.

In addition to having access to the AD FS server, you’ll need the following items:

  • A defined set of users and groups.

  • A Certificate Authority (CA) root certificate and a Signing Certificate from a valid certificate authority. You’ll import these certificates into your AD FS instance.

    These are the token certificates and corresponding private key that are imported into AD FS so that it can generate and sign SAML tokens. These certificates must also be added to the Token Certificates panel of the CSF Keys and Certificate dialog in MCS so that MCS can validate the token. These are the token certificates that will be associated with the token issuer in MCS.

For testing purposes, you can create a root certificate and a self-signing certificate as shown in the following examples but don’t use them in a production environment.

Here’s an example of how to create a root certificate:

$ openssl req -x509 -nodes -days 3650 -subj "/C=US/ST=CA/L=Local/O=SampleCA/OU=Self-Signed/CN=ca.test.local" -newkey rsa:2048 -keyout testCARootPrivateKey.key -out testCARootCertificate.crt

Here’s an example of how to create a new key pair and the corresponding certificate:

$ openssl req -nodes -days 3650 -subj "/C=US/ST=CA/L=Local/O=SampleCA/OU=Self-Signed/CN=sts-signing.test.local" -newkey rsa:2048 -keyout testSigningPrivateKey.key -out testSigningCertificate.csr

$ openssl x509 -req -days 3650 -in testSigningCertificate.csr -CA ../ca/testCARootCertificate.crt -CAkey ../ca/testCARootPrivateKey.key -CAcreateserial -out testSigningCertificate.crt

$ openssl pkcs12 -export -out testSigningCertificate.pfx -inkey testSigningPrivateKey.key -in testSigningCertificate.crt

Creating Users and Groups in AD FS

You need to create users and assign them to groups in AD FS. In MCS, these user groups are mapped to existing MCS roles. This assumes that you have the AD FS server installed.

Start AD and add users:

  1. Select Tools > Active Directory Users and Computers.

  2. Open the Active Directory and Users and Computers folder.

    This is the directory where you’ll add users and groups.

  3. Right-click the Users folder and select New > User.

  4. In the New Object - User dialog, provide a first and last name for each user you add and the user logon name. The logon name must match the user email address for that user in MCS.

    For example, if the user is John Smith, and his address is jsmith@local.domain, the address must match the email address for user John Smith in MCS.

  5. Click Next and then OK to add the user.

    Repeat these steps for each user you want to add.

To add a group and assign a user to it:

  1. Right-click the Users folder in the Active Directory and Users and Computers directory and select New > Group.

  2. In the New Object - Group dialog, enter a name for the group.

  3. Leave the default settings of Global and Security, for Group Scope and Group Type and click OK.

  4. Right-click on the user name in the Active Directory and Users and Computers directory and select Add to a group....

  5. In the Select Group dialog, click Advanced.

  6. In the advanced version of the Select Groups dialog, click Find Now.

  7. Locate the group name from the Search results list, select it, and click OK.

  8. Click OK in the Select Group dialog to complete the group assignment.

To verify that you’ve added the user to the correct group:

  1. Click on the group name in the Active Directory and Users and Computers directory to open the group’s properties dialog.

  2. In the properties dialog, click Members and look to see if the user you added is listed.

A group should have a corresponding role in MCS. The user assigned to the group would then be assigned to the corresponding MCS role.

Configuring the SAML App in AD FS

After you’ve added your users and groups and have a valid root certificate and signing certificate, you can configure the SAML token. You’ll begin by adding and configuring a relying party trust. The relying party defines the way in which AD FS recognizes the relying party application and issues claims to it.

  1. From the Server Manager, select Tools > AD FS Management.

  2. In the AD FS window, select Action > Add Relying Party Trust....

  3. Click Start in the Add Relying Trust wizard.

  4. On the Select Data Source panel, select Enter data about the relying party trust manually option.

  5. Click Next to go to the Specify Display Name panel.

  6. Enter the name of your SAML app in the Display Name field.

    This app name will be listed in the Trust Relationships > Relying Party Trust directory after you add it.

  7. Click Next to go to the Choose Profile panel.

  8. Select AD FS profile (the default value).

    This is the profile type that supports the SAML 2.0 protocol.

  9. Click Next and Next again to go to the Configure URL panel.

    You can upload the signing certificate on the Configure Certificate panel now or upload it later. You don’t need to upload an encryption certificate unless you want the SAML assertion encrypted as well as signed. Having an encrypted SAML assertion can be useful in cases where sensitive data is added to the SAML assertion claims.

  10. Select Enable support for the SAML 2.0 Web SSO protocol and enter the redirect URL in the Relying party SAML 2.0 SSO service URL field.

    The redirect URL is the address where you want the request to post back to so you can intercept the token.

  11. Click Next to go to the Configure Identifiers panel.

  12. Enter the SSO token endpoint in the Relying party trust identifier field and click Add.

    You construct this endpoint by appending /mobile/platform/sso/exchange-token to your instance’s base URL. You can determine the base URL by opening any mobile backend in MCS, clicking its Settings tab, and looking in the Environment URLs section. For example: 

    https://hostname:443/mobile/platform/sso/exchange-token

    This is how you specify the audience for the SAML assertion.

  13. Click Next to go to the Configure Multi-factor Authentication Now panel.

    Use the default setting, I do not want to configure multi-factor authentication settings for this relying party trust.

  14. Click Next to go to the Choose Issuance Authorization Rules panel.

    Use the default setting, Permit all users to access this relying party.

  15. Click Next to go to the Ready to Add Trust panel, click Next again.

  16. Click Finish.

    Leave the default setting, Open the Edit Claim Rules dialog for this relying party trust to continue configuring your SAML app.

  17. Click Close to exit the wizard.

    The Edit Claim Rules dialog opens when you exit the wizard.

Configuring Claim Rules in AD FS

The next step to configure your SAML app is setting the claim rules. The claim rule specifies how the values for LDAP attributes are mapped to the outgoing claim type. You’ll use the Add Transform Claim Rule wizard available from the Edit Claim Rules dialog to add AD claims and transform NameID transform rule which specify the claims that are sent to the relying party.

  1. Open the Relying Party Trust folder under the Trust Relationships directory and right-click your app name. Then select Edit Claim Rules.

    If you’re continuing on from the previous section, the Edit Claim Rules dialog opens automatically when you exit the Add Relying Trust wizard.

  2. Make sure the Issuance Transform Rules tab is open and click Add Rule to open the Add Transform Claim Rule wizard.

  3. In the Choose Rule Type tab, select the Send LDAP Attributes as Claims template from the drop-down list.

  4. Click Next to go to the Configure Claim Rule tab.

  5. Enter a claim rule name. For example, AD Claims.

  6. Select Active Directory as the Attribute store.

    In the next set of steps, you’ll map the LDAP attributes to the outgoing claim types:
    LDAP Attributes Outgoing Claim Type

    E-Mail Addresses

    E-Mail Address

    Token-Groups-Unqualified Name

    Group

    User-Principal-Name

    Common Name

  7. Open the LDAP Attributes list and select E-Mail Addresses.

  8. Open the Outgoing Claim Type list and select E-Mail Address.

  9. Repeat steps 7 and 8 to map Token-Groups-Unqualified Name to Group and to map User-Principal-Name to Common Name.

  10. Click Finish.

Configuring Transform Rules in AD FS

You set transform rules to map incoming claim types to outgoing claim types and specify the action that determines what output should occur based on the values from the incoming claim.

  1. Open the Edit Claim Rules dialog and open the Issuance Transform Rules tab.

  2. Click Add Rule to open the Add Transform Claim Rule wizard.

  3. In the Choose Rule Type tab, select Transform an Incoming Claim.

  4. Click Next to go to the Configure Claim Rule tab.

  5. Perform the following actions on this tab:

    • Enter Transform NameID for the transform claim rule.

    • Select EMAIL ADDRESS for the incoming claim type.

    • Select Name ID for the outgoing claim type.

    • Leave as unspecified the ingoing and outgoing nameID formats.

    • Select the Pass through all claim values option.

  6. Click Finish.

  7. Click Apply and OK in the Edit Claim Rules dialog.

Specifying the Signature Verification Certificate in AD FS

You must specify the signature verification certificates for requests from the relying party trust.

  1. Open the Relying Party Trusts folder, right-click your app name, and select Properties.

  2. In the properties dialog for your app, select Signature and click Add.

  3. In the Select a Request Signature Verification Certificate dialog, navigate to the directory where you stored (or created) the signing certificate and select the certificate.

  4. Click Open.

  5. (Optional) Click the Endpoints tab in the app properties dialog and review the SAML assertion endpoints.

    Click the endpoint URL to view its details in the Edit Endpoint dialog. The endpoint type should be SAML Assertion Consume. Set the Binding field for the type of SAML response to receive:

    • If the client expects a POST, set Binding to POST.

    • If the client expects to receive the SAML Response as a GET parameter, set Binding to Redirect.

      Note:

      There can be issues using a redirect in the case of long assertions because some browsers have limits to the length of the URL.

Integrating Microsoft Azure Active Directory with Oracle Cloud

As an example of adding a remote identity provider, here is what you do to enable use of Microsoft Azure Active Directory as the remote identity store for apps that use MCS mobile backends and which have users that have Oracle Cloud accounts.

The general sequence of steps is:

  1. In Azure, create an application and configure it to use single sign-on.

    This application will provide the context for configuring the SSO relationship and identify the set of users to whom that relationship is applicable.

  2. In Oracle Cloud, configure Azure Active Directory as the identity provider.

  3. In your Azure app, add the Oracle Cloud service provider information.

  4. In your Azure app, assign users to access the app.

  5. In Oracle Cloud, import the Azure users.

  6. In Oracle Cloud, enable the SSO configuration.

  7. In MCS, enable SSO in a mobile backend.

  8. Test the SSO with a mobile backend.

This procedure assumes that you have a Windows Azure account with Azure Active Directory Premium enabled.

Creating and Configuring the App in Azure that Will Serve as the Identity Store

The first step is to create an application in Azure and then configure that app to use single sign-on. This app doesn’t have any end-user functionality.

  1. Sign in to the Azure portal, browse to the directory you want to use, select Applications, and click Add.

  2. Select Add an application from the gallery.

  3. Select Custom, select Add an unlisted application my organization is using, provide a name, and save.

  4. On the application page, click Configure single sign-on.

  5. Select Microsoft Azure AD Single Sign-On and click Next.

  6. On the Configure App Settings page, add values for Issuer and Reply URL.

    These values are just temporary placeholders, so just enter any syntactically correct URLs, such as https://www.example.com.

    You will add the real values later once you have set up your Oracle Cloud account to use Azure Active Directory as a remote identity provider.

  7. On the Configure single sign-on at ... page, click Download Metadata (XML) and save the file as IdP-Metadata.xml.

    You will need this file to configure your Oracle Cloud account.

  8. Check Confirm that you have configured single sign-on as described above.

  9. In the next screen, confirm the notification email (optional) and save.

Configuring Azure Active Directory as the Identity Provider in Oracle Cloud

Now that you have set up the app in Azure to hold the identity store, you can configure your Oracle Cloud account to use it.

The configuration you do here will determine how an Oracle Cloud user record is identified from the information that Azure AD provides (via the SAML token).

  1. Log in to Oracle Cloud, go to Users and then SSO Configuration and click Configure SSO.

  2. In the popup window, select Import identity provider metadata and load the Azure metadata file (IdP-Metadata.xml) that you just downloaded from Azure.

  3. From the SSO Protocol dropdown, select HTTP POST.

  4. From the User Identifier dropdown, select one of the following to specify which field in the Oracle Cloud user record you will use to match with the Azure AD record.

    • User’s Email Address

    • User ID

  5. From the Contained in dropdown, select the attribute from Azure AD (such as user name or email address) that you want to be matched again the User Identifier value above.

  6. Click Save.

  7. Under Configure your Identity Provider Information, make a note of the Provider ID and Assertion Consumer Service URL values.

    You will use these values when configuring the Azure App to work with Oracle Cloud.

  8. Click Export Metadata , select Provider Metadata, and save the file.

    This metadata may come in handy later if configuration problems arise.

Adding the Oracle Cloud Service Provider Information to the Azure App

In this step, you go back to Azure and fill in the Oracle Cloud service provider information that you just generated.

  1. Go back to the Azure portal, and select your directory, then click Applications and then on the application created before.

  2. Click Configure single sign-on.

  3. Select Microsoft Active Directory again, and then click Next.

  4. In the Issuer field, enter the value of the Provider ID that you copied after configuring Azure AD as an identity provider in Oracle Cloud.

  5. In the Reply URL field, enter the value of the Assertion Consumer Service URL that you copied above.

  6. For the next steps, continue with the defaults and then save at the end.

Note:

If you have problems with the Issuer and Reply URL values, you can double-check them in the metadata you exported after configuring Azure AD as the identity provider in Oracle Cloud. The Provider ID (and thus the Issuer) value should correspond with value of the entityID attribute of the EntityDescriptor element. The Assertion Consumer Service URL (and thus the Reply URL) value should correspond with the value of the Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" attribute of the AssertionConsumerService element.

Assigning Azure Users to Access Your App

Next you populate your Azure app with the users that you want to be able to log in via the SSO feature.

  1. In the Azure portal, navigate to your directory, click Applications and choose the container application you created.

  2. Go to the Users And Groups tab, search for the groups you would like to be able to access MCS apps, and assign them by clicking the Assign button at the bottom of the page.

Importing Users Into Your MCS Realm

And now you import those users into MCS, via Oracle Cloud.

  1. Export the users from Azure, using the recommended method, depending on the source of the users.

    • If the users originate from an on-premises Active Directory installation, use the standard Active Directory tools to export them.

    • If the users originate from Azure directly, use Azure Windows Power Tools.

  2. Insert those users into a CSV file, with the following structure: First Name, Last Name, Email, User Login.

    The User Login must match the same username used to log-in to Azure.

  3. Import the users into Oracle Cloud and assign them the realm that you want to use as described in Importing Groups of Mobile Users Into MCS Using Oracle Cloud.

Enabling the SSO Configuration

Once you have assigned users for your application in Azure AD, and have imported those users into Oracle Cloud, enable the SSO Configuration by following these steps:

  1. On the Single Sign-On (SSO) Configuration page in Oracle Cloud, navigate to the Test your SSO section and click Test.

  2. If that test is successful, navigate to theEnable SSO section of the page and click Enable SSO.

Testing the SSO with an MCS Mobile Backend

Once SSO has been fully configured and enabled and you have enabled SSO in a mobile backend, you can test it with that mobile backend.

If you haven’t yet enabled SSO in a mobile backend, see Enabling Single Sign-On for a Mobile Backend.

To test SSO access to a mobile backend:

  • Open a web browser and navigate to the following URL:

    <environment URI>>/mobile/platform/sso/token?clientID=<OAuth client ID>

    where <environment URI> is the URI used to access platform APIs for the given MCS instance, and <OAuth client ID> can be obtained from the Settings page for the given mobile backend.