Certificate-based authentication in the IdP

Certificate-based authentication is enabled from the Enterprise Application Access (EAA) Management Portal in the identity provider (IdP) general settings in the Certificate Validation Settings section.

You can use certificate-based authentication for logging into the identity provider URL (login portal). A certificate, typically installed on an end user’s device or computer, is validated when the user agent establishes connection with the EAA service. After authentication, user-facing authentication mechanisms also apply. After the certificate is validated, the expected user-facing authentication mechanism also applies. For example, while configuring User-facing authentication mechanism for applications, if Form is selected as the application’s user-facing authentication mechanism, an end user must also enter their login credentials into the login form after the has been validated.

To use this feature, you must upload a trusted certificate authority (CA) to validate the end user’s certificate, and configure these settings:

  • Certificate validation. Select this option to enable certificate-based authentication for the IdP.
  • Enforcement. Set to Required (default), Optional, or Required off-network, Disabled on-network based on your desired security posture. Akamai recommends the Required setting. See Certificate enforcement settings for different use cases.
  • CA certificate issuer: Select the certificate issuer that you want to use to validate the end user’s certificate. To provide a CA see Add a certificate to EAA.
  • Certificate attribute validation. (optional) Allows EAA to check values of specific certificate attributes in client-certificates and allow only validated users to access the identity provider or applications. You can provide values to specific attributes in client certificates. See Certificate attribute validation examples for details.

  • Certificate Identity Attribute. (optional) Select the attribute to identify the user in the certificate.
  • Certificate identity is username. (optional) If the certificate identity attribute you selected above represents the username, select this option.
  • Certificate validation method. (optional) Used to verify the validity of the certificate and ensure that the certificate has not been revoked. Select OCSP if you want to check certificate revocation status using an OCSP server. You must configure a new OCSP responder, see Create an online certificate status protocol (OCSP) responder. Otherwise, leave it as None.
  • OCSP Responder. If the Certificate validation method is OCSP, obtain the OCSP responder URI from the certificate or select the OCSP responder that you defined. See Create an online certificate status protocol (OCSP) responder. This responder will be used to validate the certificate.
  • Allow Request. (optional) Allow certificate validation to complete successfully when OCSP is enabled but the OCSP responder returns Unknown or is Unreachable. This allows the end user to access the identity provider. This lowers the authentication assurance level.
  • Certificate Onboard URL. (optional) The URL where the end user is redirected if no certificate is presented for authentication.

Certificate enforcement options

This topic describes the different certificate enforcement options for your desired security posture.

After you enable certificate validation, you can use different enforcement settings to decide if the identity provider will require the end-user to provide a valid client certificate or if it is optional or if it only required when the user is off-premise.

The end-user experience for the different use-cases are:
  1. Organizations can make certificates mandatory when end users are within or outside the corporate network.
    Enforcement option is set to Required
    Enforcement = Required Valid certificate = Yes Valid certificate = No
    On network Certificate is verified. Optionally, the end user is then prompted for username and password. Since the certificate is invalid, the user is denied access.
    Off network Certificate is verified. Optionally, the end user is then prompted for username and password. Since the certificate is invalid, the user is denied access.
  2. Organizations can make certificates optional when end users are within or outside the corporate network.
    Enforcement option is set to Optional
    Enforcement = Optional Valid certificate = Yes Valid certificate = No
    On network Certificate is verified. Optionally, the end user is then prompted for username and password. Since it is optional to have a valid certificate, even if it is invalid, the user is prompted for username and password.
    Off network Certificate is verified. Optionally, the end user is then prompted for username and password. Since it is optional to have a valid certificate, even if it is invalid, the user is prompted for username and password.
  3. Organizations can make certificates mandatory when users are off the corporate network and are disabled when users are inside the office. You must also configure on premise subnets in the Advanced settings of the identity provider .
    Enforcement option is set to Optional
    Enforcement =

    Required off-network, Disabled on-network

    Valid certificate = Yes Valid certificate = No
    On network End user is on-premise and therefore certificate validation check is not done. End user is directly prompted for username and password. End user is on-premise and therefore certificate validation check is not done. End user is directly prompted for username and password.
    Off network Since a certificate is required when the end-user is off-premise, it is verified. Then, the end user is prompted for username and password. Since a certificate is required when the end-user is off-premise, and the user does not have a valid certificate, he/she is denied access.
Note:
  1. If you have configured integrated windows authentication (IWA) on the user’s machine, username and password is replaced by the Desktop SSO credentials.
  2. If you have enabled Certificate identity is username and provided a Certificate Identity attribute that can be inferred from the certificate, the end-user will not be prompted for username and password for use cases where it says, “end user is prompted for username and password” in the tables above.
  3. If you have disabled Certificate identity is username, the end-user will be prompted for username and password for use cases where it says, “end user is prompted for username and password” in the tables above.
  4. If you have set Enforcement to Required off-network, Disabled on-network and also set Bypass MFA criteria, it would work in multiple ways. When the end user is on-premises, bypass MFA will not happen since certificate authorization is skipped. MFA is prompted in this scenario. When the user is off-premises, certificate authorization is required and hence MFA can be bypassed after the end-user is authenticated.

Certificate attribute validation

Allows EAA to check values of specific certificate attributes in client-certificates and allow only validated users to access the identity provider or applications.

EAA allows you to validate values of certain specific attributes in the client certificate, allowing organizations to ensure that that certificate was indeed issued to them by an authorized issuer, prior to allowing access to the Akamai identity provider login portal.

After you have enabled Certificate validation, and Certificate attribute validation in the Akamai identity provider, you can provide allowed and denied values using regular expressions to specific attributes to validate the client certificate. If all of the certificate attributes are validated, the user is allowed access to the identity provider or application. If any of the certificate attribute validation fails, the user gets a forbidden access error message.

EAA supports these three certificate attributes for validation:

  • Serial number of the client certificate. It is normally a hexadecimal string in your certificate. If you are using openSSL oneline format, an example is:

Serial Number: 11644418304729121987 (0xa19948c0dd6f84c3)

  • Client certificate Issuer distinguished name (DN). It has information of the country, state, organization, organization unit, and common name of the issuer of the certificate. If you are using openSSL oneline format, an example is:

Issuer: C=US, ST=CA, O=DigiCert Inc, OU=DigiCert Global

  • Client certificate Subject distinguished name (DN). It has information of the country, state, location, organization, organization unit, and common name of the organization to whom the certificate is issued to. If you are using openSSL oneline format, it would appear as, an example is:

Subject: C=US, ST=CA, L=Fremont, O=Akamai, OU=EAA, CN=employee_number/emailAddress=employee_number@root.com

You can use the IS and IS Not operators on each of the above attributes. Both these operators support single or multiple regex values. If you provide multiple values, the identity provider checks if any one of the regex values matches, then it allows access to the user.

Example 1:

If you want to provide access to users with only the certificates with serial numbers (in hexadecimal format without the base specification of 0x) 1234, 1238, and 1445, you could configure the serial number certificate attribute as:

Then any of the users will be allowed access.

Example 2:

If you want to deny access to certain user who has an expired certificate of a specific serial number you can specify the criteria as:

Then that user will be denied access.

Example 3:

You can use the same attribute multiple times using AND logic. For example, you want to allow access to all users in example 1 and deny access to the user in example 2, you can create a more complex criteria as:

Example 4:

You might want employees from only two organization units, Dev and QA, to access your identity provider and applications, and deny access to others. Your Subject DN might look like this in the certificates of the two organizations:

Subject DN for organization unit Dev:

Subject: C=US, O=Akamai Technologies, OU=Dev, CN=employee_number/emailAddress=employee_number@root.com

Subject DN for organization unit QA:

Subject: C=US, ST=CA, O=Akamai Technologies, OU=QA, CN=employee_number/emailAddress=employee_number@root.com

You can create a regex expression - starts with the country of USA, has Organization of Akam followed by any characters, contains either Dev or QA organization units, and ends with .com - ^\/C=US\/.*\/O=Akam+.*\/OU=(Dev|QA).*\.com$, for the criteria for the subject DN:

Example 5:

You might want to only allow access to all US employees within your organization (subject) having valid unexpired certificates, issued by a certain organization (Issuer) to access the identity provider and apps, except for two employees with expired certificates.

You’re issuer DN, subject DN and expired certificates maybe of the format:

Issuer DN: Details of the organization that issued the certificate:

Issuer: C=US, O=DigiCert Inc, CN=DigiCert Global

Subject DN: Details of the subject or organization to whom the certificate was issued to:

Subject: C=US, O=Akamai Technologies, CN=employee_number/emailAddress=employee_number@root.com

Serial numbers of ex-employees with expired certificates:

Serial Number: 1234

Serial Number: 1135

You can create a regex expression combining all the three attributes as shown below:

Example 6:

If you have one division of your organization in Fremont location and another division of your organization in Sunnyvale location and you want to allow access to applications on an identity provider, but you do not want any contractors from India location or Cambridge Massachusetts location, you can create regular expressions as under:

Subject DN for Fremont location employees may look like:

Subject: C=US, ST=CA, L=Fremont, O=Akamai, OU=EAA, CN=employee_number/emailAddress=employee_number@root.com

Subject DN for Sunnyvale location employees may look like:

Subject: C=US, ST=CA, L=Sunnyvale, O=Akamai, OU=EAA, CN=employee_number/emailAddress=employee_number@root.com

Subject DN for Cambridge location employees may look like:

Subject: C=US, ST=MA, L=Cambridge, O=Akamai, OU=EAA, CN=employee_number/emailAddress=employee_number@root.com

Subject DN for Bangalore location employees may look like:

Subject: C=IN, ST=KA, L=Bangalore, O=Akamai, OU=EAA, CN=employee_number/emailAddress=employee_number@root.com

You can create your criteria as under:

Limitations

Admin should provide a backslash escape character (\) for each of the C, ST, L, O, OU, and CN values even for exact matches of Subject DN and Issuer DN.

For example:

Following exact match will result into an error:

/C=US/ST=CA/L=Fremont/O=Akamai/OU=EAA/CN=employee3/emailAddress=employee3@root.com

The regex should be created as:

\/C=US\/ST=CA\/L=Fremont\/O=Akamai\/OU=EA\/CN=employee3/emailAddress=employee3@root.com

Configure certificate-based authentication for the IdP

Complete this procedure to enable and configure certificate-based authentication for an identity provider (IdP).

How to

  1. Add a certificate to EAA
  2. If you want to use an OCSP server to validate the certificate, see Create an online certificate status protocol (OCSP) responder in EAA.
  3. Select the identity provider you want to enable certificate-based authentication for the identity provider.
  4. Click the Settings (gear icon) to modify or configure the settings of the IdP.
  5. In the IdP GENERAL tab, go to the Certificate Validation Settings section.
  6. Enable Certificate validation. The Enforcement and CA certificate issuer fields appear.
  7. Select any one of the Enforcement settings:
    • Required (default). The IdP requires the client to present a valid client certificate for authentication that has been issued by a trusted root CA and can be validated by the root CA. If no certificate is presented the user will see an 400 HTTP error in the browser.
    • Optional. It is optional for the client to present a valid client certificate for authentication that has been issued by a trusted root CA.If a valid client certificate is presented, the user logs in. Otherwise, form-based login is used as the fall-back mechanism.
    • Required off network, Disabled on network. Select this option if you conditionally want to apply certificate based authentication only when the user is not on premise. You must configure on-premise subnets in the Advanced Settings of this identity provider. Also, see Certificate enforcement options.
  8. Certificate attribute validation. Select this option if you want to validate values of certain specific attributes in the client certificate. Click Add Attribute. Select the certificate attribute, it can be the client certificate’s serial number, the issuer’s distinguished name (DN), or the subject’s distinguished name (DN), select a logical operator, and add any regular expression (regex values). You can also repeat the same attribute multiple times.To add another attribute, click Add Attribute and repeat this step, till you have finished adding all attributes. See certificate attribute validation examples for more details.
  9. CA certificate issuer. Select the root CA that you want to use to validate the end user’s certificate.
  10. Certificate Identity Attribute. Select the attribute to identify the user in the certificate.
  11. Certificate identity is username. (Optional) Select this option, if the certificate identity attribute represents the username. If you have enabled Certificate identity is username and provided a Certificate Identity attribute that can be inferred from the certificate, the end-user will not be prompted for username and password credentials. Otherwise, the user is presented a login form for authentication. Also, see Certificate enforcement options.
  12. Certificate validation method. Select either None(default) or OCSP. If you select OCSP, the OCSP Responder and Allow Request fields appear.
    1. Select an OCSP Responder from the list. If you do not select on OCSP responder, the OCSP responder URI is picked from the certificate.
    2. Allow Request (Optional) You can select any of these options:
      • OCSP responder returns Unknown. (Optional) Allows the end user to access the application, even when, for example, the OCSP server cannot find the certificate’s serial number in it’s database.
      • OCSP responder returns Unreachable. (Optional) Allows the end user to access the application, even when the OCSP server is down.
      Note: Akamai does not recommend using the options OCSP responder returns Unknown or OCSP responder returns Unreachable since it reduces authentication assurance level.
  13. Certificate Onboard URL. (Optional) Enter the URL where the user is redirected if no certificate is provided.
  14. Certificate expiration duration warning. (Optional) Specify the number of days you want a warning to appear for the end user before the certificate expires.
  15. To save the changes click Save and exit or Save and go to directories.
  16. For changes to go into effect, Deploy the identity provider