Managing certificate providers

Certificate-based identity provides access to precise insights while it connects external certificates providers with an extra security layer such as a X.509 compliant digital certificate. It authenticates using the digital certificate with IBM® Security Verify when it accesses the connected applications. Administrators can verify identities by using this digital signature for authentication and compliance purposes. In addition, certificates might work with common access (CAC) or personal identity verification (PIV) card.

Before you begin

You must have administrative permission to complete this task.
Log in to the IBM Security Verify administration console as an Administrator.
To be able to use the certificate provider, your tenant must have a vanity hostname. See Obtaining a vanity hostname.

You need to provide the root and the intermediate certificates through the support route:

If your tenant is created and has a vanity hostname that is properly configured, contact IBM Security Verify by opening a ticket through IBM support team, and you will be notified on how to provide the certificates.
You must keep the certificates in X.509 PEM encoded format.
This is an example:

# Trust chain intermediate certificate
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgILBAAAAAABRE7wQkcwDQYJKoZIhvcNAQELBQAwVzELMAkG
C33JiJ1Pi/D4nGyMVTXbv/Kz6vvjVudKRtkTIso21ZvBqOOWQ5PyDLzm+ebomchj
SHh/VzZpGhkdWtHUfcKc1H/hgBKueuqI6lfYygoKOhJJomIZeg0k9zfrtHOSewUj
...
dHBzOi8vd3d3Lmdsb2JhbHNpZ24uY29tL3JlcG9zaXRvcnkvMDMGA1UdHwQsMCow
KKAmoCSGImh0dHA6Ly9jcmwuZ2xvYmFsc2lnbi5uZXQvcm9vdC5jcmwwPQYIKwYB
K1pp74P1S8SqtCr4fKGxhZSM9AyHDPSsQPhZSZg=
-----END CERTIFICATE-----

# Trust chain root certificate
-----BEGIN CERTIFICATE-----
MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG
YWxTaWduIG52LXNhMRAwDgYDVQQLEwdSb290IENBMRswGQYDVQQDExJHbG9iYWxT
aWduIFJvb3QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDaDuaZ
...
jc6j40+Kfvvxi4Mla+pIH/EqsLmVEQS98GPR4mdmzxzdzxtIK+6NiY6arymAZavp
38NflNUVyRRBnMRddWQVDf9VMOyGj/8N7yy5Y0b2qvzfvGn9LhJIZJrglfCm7ymP
HMUfpIBvFSDJ3gyICh3WZlXi/EjJKSZp4A==
-----END CERTIFICATE-----

Note: For more information about PEM encoded format, see RFC 1421

Receive confirmation that the certificate chain has been configured properly with the vanity hostname on your tenant. After you receive confirmation, you can use the issued client certificate for SAML and OIDC authentication as well as your user launchpad.

Note: A publicly accessible CRL distribution or OCSP endpoint (saved in the client certificate) is necessary for the client certificate authentication to work.

About this task

Verify supports access to several capabilities that accomplish complex tasks. Such as own base service providers and other application interfaces that are commonly used for developing custom service providers. X.509 digital signature certificate provides many benefits. Two important are certificate revocation lists and certification path validation algorithm eventually reaching a trust anchor.

Note: For more information about X.509 digital signature certificate, see X.509 certificates. For a deeper review, see RFC 5280.

Procedure

Select Authentication > Certificate providers
Select Add certificate provider.
Provide the General settings.
1. Give an easily recognizable name to the certificate provider and set the identity provider.
2. Select an identity provider that is used to authenticate the user. The commonly used identity providers are:
  - Cloud Directory
  - IBMid
  Note: You cannot change the identity provider after the certificate provider is created.
3. Select the JITP (Just in time provisioning) check-box to provision user accounts.
Click Next.
Configure User properties. You must specify the user attributes that are sent from the certificate to authenticate users and to create user profiles.
1. Optional: Select Certificate attribute.
  
  Note: User can add multiple rows.
2. Select IBM Security Verify attribute. This selection is based in past attributes that are selected or created by the administrator.
  Note:
  You can choose one option from the existing attributes. The attribute by default is
  None - Do not map
  If you choose None - Do not map, you are not able to configure:
  - Transformation value
  - Store attribute in user profile
3. Select a Transformation value from the menu.
4. Select an option from the Store attribute in user profile menu.
  - Always - Store or update the attribute at each login.
  - On user creation only - Store the attribute once at account creation.
  - Disabled - Never store or update the attribute.
  After you configure the first user attributes, click Add attribute mapping to add more mappings.
  Note: You can add as many attribute mappings as you prefer.
5. Select Unique user identifier. This identifier is the certificate attribute that is used to link to an existing user in the Verify identity provider.
6. Compute the attribute value by creating a custom rule in Request rule option.
  An example of a sample rule:
```
requestContext.subjectAlternativeNameEmail.size() != 0 ? requestContext.subjectAlternativeNameEmail[0].split('@')[0] : requestContext.subjectCN[0].split('.')[0]
```
  Test your request rule to make sure it works as intended. Click Run test to the result. It is the return value based on the sample inputs.
For the Certificate chain, complete these steps to provide the subject key identifier of the issuing intermediate or root certificate authority.
1. Find the Subject Key Identifier of the immediate certificate authority by using the following Openssl command:
```
openssl x509 -inform pem -in $input-filename -text -noout
```
2. Click the section with label "X.509v3 extensions" and select "X.509v3 Subject Key Identifier". Copy and provide the specified value in the box.
  
  Note: This value cannot be changed after the certificate provider is created.
Test the configuration. Select. Next. The interface provides you with a Tenant authentication URL. You must copy the URL and try to connect to your IBM Security Verify.
Note: You need to enable the certificate provider before using it in your IBM Security Verify tenant.
Click complete setup. A prompt redirects you to the global settings to manage or update some information that is related with the configuration.
Optional: Click Certificate providers to see the list of your certificate providers created.
1. You can click List of options to enable or delete the certificate provider that you want to use.

Troubleshooting

If the configuration does not works, it might be for the following reasons:

If all the steps for onboarding an X.509 certificate provider are completed, and you are not able to see the certificate prompt when does access the test URL in the test configuration page:

Ensure that a vanity hostname is being used.
Ensure that the certificate chain is provided to IBM Security Verify through the support route.

If all the steps for onboarding a X.509 certificate provider are completed, and you are not able to see the certificate prompt when does access the test URL in the test configuration page, but authentication not works:

Ensure that the certificate provider is enabled.
If the JITP is enabled, ensure that the user is created in the specified identity provider.
If the JITP is disabled, ensure that the user exists in the specified identity provider.

If uniqueUserIdentifier attribute is changed after the X.509 certificate provider onboard, then it is applicable only to the new authentications and users that authenticate with a certificate for the first time.

If the JITP is enabled, then for users created in the specific identity provider for the first time.

By default a X.509 certificate provider is disabled, administrators must enable it before they try the test configuration.