Apply an app-specific, on-demand MFA policy

Enforcing MFA policies for launching applications typically requires users to first authenticate to the Identity service. For use cases where you want to secure apps with MFA without requiring users to first authenticate to the Identity service, you can use the OAUTH confidential client flow to generate a bearer token for use with the /security/GetTokenForUser endpoint in combination with a query for a username. A POST request to /security/GetTokenForUser?user=<username> returns a temporary bearer token for that user that you include in the header of a POST request to <tenantURL>/run?appkey=<appkey>.

Add and deploy an app

Refer to Apply_authentication_profiles_to_applications for details.

Note the value for the App Key on the Description page.

Create an OAuth confidential client and client app

The following steps describe how to add a confidential client user and configure a OAuth Client app. Refer to Client Credentials Flow for more detail.

Add a confidential client user

1. In the Admin Portal, go to Core Services > Users, then click Add User.

2. Complete the required fields, then select Is Service User and Is OAuth confidential client.

   Remember the user's password!

3. Click Create User.

4. Go to Core Services > Roles, then open the System Administrator role.

5. Add the confidential client user to the System Administrator role, then click Save.

Configure an OAuth Client app

1. In the Admin Portal, go to Apps > Web Apps, then click Add Web App.

2. On the Custom tab, click Add next to OAuth Client, then click Close.

   The OAuth Client app displays.

3. Complete the required fields on the Settings page.

   Note the Application ID value; you will need this value later to get a bearer token.

4. On the Tokens page, select only Client Creds.

5. On the Scope page, click Add to add a scope definition.

6. Name the scope, then enter security/GetTokenForUser for the scope regex and save your changes.

   This restricts the app's access to only the /security/GetTokenForUser endpoint.
   Note the scope name; you will need this value later to get the bearer token.

7. On the Permissions page, add the confidential client user created previously, then click Save.

Get a bearer token

1. Send a POST request to {{baseUrl}}/token/{{Application ID}} where `{{Application ID}} is the Application ID of your OAuth Client app.

   Send the request payload as form-data using the following key-value pairs:
   scope: {{scope name}}
grant_type: client_credentials
client_id: {{OAuth confidential client Login Name}}
client_secret: {{password for OAuth confidential client}}

   Note Remember to secure the client_id and client_secret in any application you design.
   For example, in Postman:

2. Copy the value for access_token in the response to your clipboard.

   This is your bearer token. You will use the token to retrieve a cookie for a specified user.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkUxRjA0N0M5NzlDMzg5NkYwQzdCQzQ2MkI0NTQ0N0ExODg0NDBDNzYiLCJ4NXQiOiI0ZkJIeVhuRGlXOE1lOFJpdEZSSG9ZaEVESFkiLCJhcHBfaWQiOiJlcGljIn0.eyJpc3MiOiJodHRwczovL2FhYTU0NTIubXkuaWRhcHRpdmUucWEvIiwiaWF0IjoxNjA5MzY1MTUxLCJhdWQiOiJjNTM5OTZkMC03NDFhLTRkYWItYmEyMi1kM2Q5MWU2M2U4MDUiLCJ1bmlxdWVfbmFtZSI6Im9uZGVtYW5kbWZhQGV4YW1wbGUuY29tIiwiZXhwIjoxNjA5MzgzMTUxLCJzdWIiOiJlZmU1ZTk1Zi0zMDRmLTQ0ZTYtYmJiNS1lNWY5YzEyMzAyNDciLCJzY29wZSI6IkdldFRva2VuIn0.ZY9x4OBpF-RI2dKtzC5gR_oYcom9jBU12J7DR4ikChL5B0RHWn4hU-S0vfZYq2iuTsejvGPUjqq2aJjIdlOawFroao26mj09THAKaMTmGxCm7l8ZJ0wBVRrVgvViy6_Ah2M0GuPzi1J3vntiw4mQyQ-6dXCr_xJODLWbchDgc1F0sJ8h5U-xkUwxYN77tgwsoryywRLhV2PvU6fV48NqX6l6T0XRyRaxgUw2PG-mNEf6nGYFJoeVZqrpN3wy6w0gNxXeXvEU9BP8OwDifXzGFF19Jfl4K-Hu43Z24tpK6HIDAaqU3rQGs77Xt_D_PzSogEOsHrACZCb-TKmVimdpDw",
    "token_type": "Bearer",
    "expires_in": 18000,
    "scope": "GetToken"
}

Retrieve a cookie for a specified user

1. Send a POST request to the /security/GetTokenForUser endpoint with the parameter user= to get a bearer token for that user.

   For example:
   POST https://mytenant.idaptive.app/Security/[email protected]

2. In the response, look for a cookie with the Name `icbt' and copy its corresponding value.

   This is cookie is valid for ten minutes.

You need the icbt cookie value to use as a bearer token and skip the user authentication to proceed straight to the MFA challenges configured for the specified app. Its scope is limited to launching the MFA challenges for the specified app; it cannot access any other APIs.

Launch the app

In a browser, add a header to include the previously obtained cookie value as a bearer token and go to {{baseURL}}/run?appkey=<appkey>.

https://mytenant.idaptive.app/run?appkey=de37dd4e-e7a4-4b88-97f0-fb60a7691fff

For testing purposes, you could use a Chrome extension to add the header with the cookie value as the bearer token using the syntax Authorization = Bearer <cookie value>. For example, in ModHeader:

The result is the MFA challenge window specified in the app's policy. The user can now complete the challenge and launch the app.

Redirect failed authentication

Add the parameter `failureRedirectUrl= to the login URL to redirect users who fail an authentication challenge. The following example redirects to the CyberArk homepage if the user fails a challenge.

https://mytenant.idaptive.app/run?appkey=de37dd4e-e7a4-4b88-97f0-fb60a7691fff&failureRedirectUrl=https://www.cyberark.com