Certificate-based authentication in the IdP

Certificate-based authentication is enabled from the Enterprise Application Access (EAA) in Enterprise Center, in the identity provider (IdP) general settings.

You can use certificate-based authentication to log in to the identity provider URL (login portal). A certificate, typically installed on an user's device or computer, is validated when the user agent establishes connection with the Enterprise Application Access 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, user must also enter their login credentials into the login form after the has been validated.

To use this feature, upload a trusted certificate authority (CA) to validate the user's certificate, and configure the following:

  • 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. Required setting is recommended.

  • Certificate attribute validation(optional). Allows Enterprise Application Access to check values of specific certificate attributes in client-certificates, and allows only validated users to access the identity provider or applications. You can provide values to specific attributes in client certificates.

  • CA certificate issuer. Select the certificate issuer that you want to use to validate the user's certificate. To provide a CA see Add, edit, and delete certificates.

  • 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. 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. For more information see Create an online certificate status protocol (OCSP) responder. This responder is 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. User can access the identity provider, but this lowers the authentication assurance level.

  • Certificate Onboard URL. The URL where the user is redirected if no certificate is presented for authentication.

  • Certificate identity is username. Leave it unselected.

Certificate enforcement options

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

The user experience for the different cases are:

  • Organizations can make certificates mandatory when users are within or outside the corporate network. Below tables summarizes configuration for Enforcement option set to Required.
Enforcement = RequiredValid certificate = YesValid certificate = No
On networkCertificate is verified. Optionally, the user is then prompted for username and password.Since the certificate is invalid, the user is denied access.
Off networkCertificate is verified. Optionally, the user is then prompted for username and password.Since the certificate is invalid, the user is denied access.
  • Organizations can make certificates optional when users are within or outside the corporate network. Below tables summarizes configuration for Enforcement option set to Optional.
Enforcement = OptionalValid certificate = YesValid certificate = No
On networkCertificate is verified. Optionally, the 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 networkCertificate is verified. Optionally, the 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.
  • Organizations can make certificates mandatory when users are off the corporate network and are disabled when users are inside the office specified by configuring On Network Zones.

    • To configure a new network zone, select Add New Network Zone, provide a network zone name, add an IP/CIDR or a comma-separated list of IPs/CIDRs, select Add new Network Zone to the list upon created, and Save. Your newly configured network zone should be selected for bypass MFA criteria.

    • To use an existing network zone, select Manage Network Zones, select the network zone from the list, and click Save. Your existing network zone should be selected for bypass MFA criteria.

    • If you have the IPs/CIDRs as a .csv file on your machine, you can upload it using the import icon.

Below table summarizes configuration for Enforcement option set to Required off-network, Disabled on-network.

Enforcement =

Required off-network, Disabled on-network

Valid certificate = YesValid certificate = No
On network. User is on-premise (within the network zones specified in On Network Zones) and therefore certificate validation check is not done. User is directly prompted for username and password.User is on-premise (within the network zones specified in On Network Zones) and therefore certificate validation check is not done. User is directly prompted for username and password.
Off networkSince a certificate is required when the user is off-premise, it is verified. Then, the user is prompted for username and password.Since a certificate is required when the user is off-premise, and the user does not have a valid certificate, he/she is denied access.
  • If you have configured integrated windows authentication (IWA) on the user's computer, username and password is replaced by the Desktop SSO credentials.

  • If you have enabled Certificate identity is username and provided a Certificate Identity attribute that can be inferred from the certificate, the user is not prompted for username and password for use cases where it says, "user is prompted for username and password" in the tables above.

  • If you have disabled Certificate identity is username, the user is prompted for username and password for use cases where it says, "user is prompted for username and password" in the tables above.

  • 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 user is on-premises, bypass MFA does 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 user is authenticated.

Certificate attribute validation

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

Enterprise Application Access 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 (IdP), 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.

Enterprise Application Access supports the following certificate attributes for validation:

  • Serial number of the client certificate. It is normally a hexadecimal string in your certificate. If you use openSSL one-line format, for example:

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 one-line format, for example:

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 one-line format, it would appear as, for example:

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 following the below table.

Certificate Attribute

Operator

Regular expression

Serial number

is

1234, 1238, 1445

Then any of the users are 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 following the below table.

Certificate Attribute

Operator

Regular expression

Serial number

is NOT

0b896ddbcce7dabe9ecea34ae35a612f

Then that user is 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:

Certificate Attribute + AND

Operator

Regular expression

Serial number

is

1234, 1238, 1445

Serial number

is NOT

0b896ddbcce7dabe9ecea34ae35a612f

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 follow the below table.

Certificate Attribute

Operator

Regular expression

Client cert subject DN

is

^/C=US/./O=Akam+./OU=(Dev|QA).*.com$

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 previous employees with expired certificates:

Serial Number: 1234

Serial Number: 1135

You can create a regex expression with AND to combine all the three attributes. Follow the below table.

Certificate Attribute + AND

Operator

Regular expression

Client cert issuer DN

is

^/C=US/./O=DigiCert+./CN=*.Global$

Client cert subject DN

is

^/C=US/./O=Akam+..com$

Serial number

is NOT

1234, 1135

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 with AND to combine all the three attributes.

Limitations:
You 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 results in 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

Enable and configure certificate-based authentication for an identity provider (IdP).

  1. Add a certificate to EAA in Enterprise Center.

  2. If you want to use an OCSP server to validate the certificate, see Create an online certificate status protocol (OCSP) responder

  3. In the Enterprise Center navigation menu, select Application Access > Identity & Users > Identity Providers.

  4. Select the IdP that you want to enable certificate-based authentication and click to open it.

  5. In Settings tab scroll down to the Certificate Validation section.

  6. Enable Certificate validation. The Enforcement and CA certificate issuer fields appear.

  7. Select any one of the Enforcement settings. You can also see Certificate enforcement options.:

    A. 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 gets a 400 HTTP error in the browser.

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

    C. Required off network, Disabled on network. Select this option if you conditionally want to apply certificate-based authentication only when the user is not within certain network zones. If the user is within these network zones, then certificate-based authentication is not enforced.

    • To configure a new network zone, select Add New Network Zone, provide a network zone name, add an IP/CIDR or a comma-separated list of IPs/CIDRs, select Add new Network Zone to the list upon created, and Save. Your newly configured network zone should be selected for certificate enforcement criteria.

    • To use an existing network zone, select Manage Network Zones, select the network zone from the list, and click Save. Your existing network zone should be selected for certificate enforcement criteria.

    • If you have the IPs/CIDRs as a .csv file on your machine, you can upload it using the import icon.

  8. Certificate attribute validation (optional). Allows Enterprise Application Access 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.

  9. CA certificate issuer. Select the root CA that you want to use to validate the user's certificate.

  10. In 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 user is not 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 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 user to access the application, even when the OCSP server is down.

    πŸ“˜

    Options OCSP responder returns Unknown or OCSP responder returns Unreachable** are not recommended since they reduce 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 user before the certificate expires.

  15. Click Save.

  16. Deploy the IdP.


Did this page help you?