Authorization Parameters

The previous article has listed and briefly explained each type of application that can be built on top of the Ability Platform. In this article, you will see the parameters that you will need to go through to implement the OAuth 2.0 flows of authorization.

Azure Active Directory B2C

Azure AD B2C is a PaaS (Platform-as-a-Service) offering from Microsoft that acts as an identity provider abstraction. You can treat AAD B2C as a facade for identity providers communication. Your users (members of the tenants that are contracted to use your solution) could be utilizing various identity providers (i.e., Azure Active Directory, Google Identity, Salesforce, etc.). When developing your app, you should not be bothered by the details of each of these providers. Thanks to the usage of AAD B2C, your only concern is to properly implement the communication with AAD B2C itself. It will handle the specific identity provider's requirements for you. The service builds on top of the OpenID Connect (OIDC) and OAuth2 standards. It contains the following features that the Ability Platform can utilize:

• customization of sign-in pages for Ability tenants;
• selection of identity providers for Ability tenants;
• capability to sign-in and issue "access tokens" that include access policies as a part of the token;
• authentication via social identity providers (e.g., Google, Facebook).

We recommend you follow the MSDN instructions on how to get access tokens for your apps. Appropriate links have been provided in the Application Authorization article. To get the access tokens, you will need to provide the B2C service with the parameters listed in this article.

Tenant Policy Types

Ability Platform is multi-tenant. It means that one platform deployment that you own may be used to serve multiple separate customers. To enable you to support many customers and to overcome Azure AAD B2C's limitations, Ability Platform has a concept of tenant policy types. There are two types:

• dynamic
• static

The dynamic policies may only be used with the Azure Active Directory identity provider. Dynamic policies are recommended if your customer uses AAD. The dynamic policy makes it possible to reuse one AAD B2C policy for multiple tenants that use Azure Active Directory.

The static policies shall be used whenever your customer uses any other identity provider than Azure Active Directory.

The policy type selection occurs while creating a tenant in the Admin Portal (or Principal Manager API, which is used internally by the Admin Portal).

OAuth 2.0 Parameters

Various OAuth 2.0 flows require different parameters to achieve the goal of getting an access token. These parameters include:

• client Id
• client secret
• authorization code URL
• token URL
• scope
• redirect URL

Depending on the flow you're using, you will need a selected subset of the parameters above. Some of these parameters can be found in the Admin Portal:

1. Client Id is automatically generated for you when you create a new application identity.
2. Client Secret is automatically generated for you when you create a new application identity. It is hidden by default, and you can view it or copy it using the buttons on the right.
3. Redirect URI is to be defined by you while creating (or editing) an app. It is used by the Authorization Code Flow (and its PKCE variant) and implicit grant flow of OAuth 2.0.

The three parameters above and all the others are described below.

Client Id

Every kind of app will require a Client ID. It is a unique identifier of your app. You will need to send it to the AAD B2C while requesting an access token.

You will find the value of the secret in the Admin Portal, as shown already.

Client Secret

This parameter is required only by the following flows:

• Authorization Code (Web app)
• Client Credentials (Background app)

This parameter should be protected from anyone - only your application should have access to it. You will find the value of the secret in the Admin Portal, as shown already.

Authorization Code URL and Token URL

These parameters are needed by the following flows:

• Authorization Code (Web App) needs both of them
• Authorization Code with PKCE (Native App) needs both of them
• Implicit Grant flow (Single Page App) needs only the Token URL
• Client Credentials flow (Background App) needs only the Token URL

OAuth 2.0 specifies that an app should first request for an authorization code (using the URL being discussed here) and then use that code to exchange it for an access token (using the Token URL, discussed next). In the case of Implicit Grant apps and Client Credentials apps, the token should be requested directly, without using any authorization code.

The format of the Authorization Code URL depends on the tenant policy type that your target tenant uses (either "static" or "dynamic").

For the "static" policy, the URL is as follows:

https://{B2C_TENANT_NAME}.b2clogin.com/{B2C_TENANT_NAME}.onmicrosoft.com/B2C_1A_{TENANT}_RP/oauth2/v2.0/authorize

For the "dynamic" policy, the URL is as follows:

https://{B2C_TENANT_NAME}.b2clogin.com/{B2C_TENANT_NAME}.onmicrosoft.com/B2C_1A_AAD_RP/oauth2/v2.0/authorize?tenant={TENANT}

Usage of dynamic policies

As we've mentioned before, the "dynamic" policy is only usable when your tenant uses Azure Active Directory (AAD). As you can see, in the "dynamic" policy type, the tenant's name needs to be provided as a query parameter.

The format of the Token URL also depends on the choice of the policy type. Here's the Token URL that you should use with the "static" policies:

https://{B2C_TENANT_NAME}.b2clogin.com/{B2C_TENANT_NAME}.onmicrosoft.com/B2C_1A_{TENANT}_RP/oauth2/v2.0/token

Here's the Token URL that you should use with the "dynamic" policies:

https://{B2C_TENANT_NAME}.b2clogin.com/{B2C_TENANT_NAME}.onmicrosoft.com/B2C_1A_AAD_RP/oauth2/v2.0/token

TIP

The "tenant" query parameter is not needed in the Token URL when using the "dynamic" policy type. It was required only for the Authorization URL.

To build the URLs presented above you will need the following data:

• the name of your B2C tenant;
• the name of the tenant that the app's user is coming from (this tenant must have a contract with your solution in the Admin Portal). If the name contains spaces, replace them with dashes ("-").

Multitenant apps

If your app is supposed to serve customers from multiple tenants (or, in other words - if your application is multitenant), the authorization URLs will need to be generated dynamically since their form depends on the name of the tenant where the user resides. An example of such an application is the Admin Portal. The first view that you see when you navigate to the Portal is an input where you need to provide your tenant name. Based on that, Admin Portal builds proper authorization URLs to get an access token for you.

Scope

This parameter is needed by every OAuth 2.0 flow. Its format is presented below:

• to access Instance APIs:

  https://{B2C_TENANT_NAME}.onmicrosoft.com/{SOLUTION_NAMESPACE}/instance
  

• to access Region (aka Principal Manager) APIs:

  https://{B2C_TENANT_NAME}.onmicrosoft.com/{SOLUTION_NAMESPACE}/region
  

You will need to gather the following values:

• the name of your B2C tenant;

• the namespace of the solution where your application identity was defined. You can find it in the "Details" tab of your solution:

  

Redirect URL

This parameter is needed by all of the flows but the Client Credentials (Background app) one.

As it was already mentioned, it is defined while creating your application identity in the Admin Portal.

Log In Outcomes With/Without Contracts

If a tenant user attempts to login to a solution that does not have a contract with the tenant, the GET /b2c/permissions API returns no permissions/conditions which effectively results in the user not having access to anything in the solution.

If a tenant user attempts to login to a solution (for which a contract is available):

• Authentication works as usual, and the tenant user receives a JWT token with permissions and conditions.

If a tenant user attempts to login to a solution (for which a contract is not available):

• User Authentication is successful. However, the user does not receive any permissions or conditions in the JWT Token.