Skip to main content
Previous section

Certificates and JWTs (JSON Web Tokens)

Each party in OAuth 2.0 requires public/private key pairs. In release 2016.2, it was necessary to use certificates (and their private keys). For reasons of compatibility, this release still contains the options related to certificates. This appendix provides the details for each of the following scenarios.

In each case, to generate the private keys and corresponding certificates, you can use the InterSystems public key infrastructure, which is discussed in the Caché Security Administration Guide.

Note:

As of release 2017.1, Caché can generate a pair of JWKSs (JSON web key sets). One JWKS is private and contains all the needed private keys (per algorithm) as well as the client secret for use as a symmetric key; this JWKS is never shared. The other JWKS contains the corresponding public keys and is publicly available. If you want to use the option of generating JWKSs, ignore this appendix.

Using Certificates for an OAuth 2.0 Client

An OAuth 2.0 client can receive JWTs (which might be encrypted, signed, or both) from the authorization server. Similarly, the client can send JWTs (which might be encrypted, signed, or both) to the authorization server. If you would like to use certificate/private key pairs for these purposes, consult the table below to determine which certificates you need:

Scenario Requirement for Client Configuration
Client needs to verify signatures of JWTs sent by authorization server Obtain a certificate owned by the authorization server, as well as the CA (certificate authority) certificate that signs the server certificate. The public key in this certificate is used for signature verification and encryption.
Client needs to encrypt JWTs sent to authorization server
Client needs to sign JWTs before sending to authorization server Obtain a private key for the client, as well as the corresponding certificate and the CA certificate that signs the certificate. The private key is used for signing and decryption.
Client needs to decrypt JWTs sent by authorization server

In each case, it is also necessary to do the following on the same instance that contains the client web application:

  • Provide trusted certificates for Caché to use. See “Providing Trusted Certificates for Caché to Use” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services. The trusted certificates must include the certificates that sign the client’s certificate and the authorization server’s certificate (either or both, depending on which certificates you need).

  • Create a Caché credential set that enables Caché to use the certificate. See “Creating and Editing Caché Credential Sets” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services.

    For the client certificate, when you create the credential set, be sure to load the private key and provide the password for the private key.

  • When you configure the client, select the option Create JWT Settings from X509 credentials. Also specify the following:

    • X509 credentials — Select the credential set that uses the client’s certificate and that contains the corresponding private key (for example, ClientConfig).

    • Private key password — Enter the password for the private key for this certificate.

Using Certificates for an OAuth 2.0 Resource Server

An OAuth 2.0 resource server can receive JWTs (which might be encrypted, signed, or both) from the authorization server. Similarly, the resource server can send JWTs (which might be encrypted, signed, or both) to the authorization server. If you would like to use certificate/private key pairs for these purposes, consult the table below to determine which certificates you need:

Scenario Requirement for Resource Server Configuration
Resource server needs to verify signatures of JWTs sent by authorization server Obtain a certificate owned by the authorization server, as well as the CA certificate that signs the server certificate. The public key in this certificate is used for signature verification and encryption.
Resource server needs to encrypt JWTs sent to authorization server
Resource server needs to sign JWTs before sending to authorization server Obtain a private key for the resource server, as well as the corresponding certificate and the CA certificate that signs the certificate. The private key is used for signing and decryption.
Resource server needs to decrypt JWTs sent by authorization server

In each case, it is also necessary to do the following on the same instance that contains the resource server web application:

  • Provide trusted certificates for Caché to use. See “Providing Trusted Certificates for Caché to Use” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services. The trusted certificates must include the certificates that sign the resource server’s certificate and the authorization server’s certificate (either or both, depending on which certificates you need).

  • Create a Caché credential set that enables Caché to use the certificate. See “Creating and Editing Caché Credential Sets” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services.

    For the resource server’s certificate, when you create the credential set, be sure to load the private key and provide the password for the private key.

  • When you configure the resource server, select the option Create JWT Settings from X509 credentials. Also specify the following:

    • X509 credentials — Select the credential set that uses the resource server’s certificate and that contains the corresponding private key (for example, ResourceConfig).

    • Private key password — Enter the password for the private key for this certificate.

Using Certificates for an OAuth 2.0 Authorization Server

An OAuth 2.0 authorization server can receive JWTs (which might be encrypted, signed, or both) from its clients. Similarly, it can send JWTs (which might be encrypted, signed, or both) to its clients. If you would like to use certificate/private key pairs for these purposes, consult the table below to determine which certificates you need:

Scenario Requirement for Authorization Server Configuration
Authorization server needs to verify signatures of JWTs sent by a client Obtain a certificate owned by that client, as well as the CA certificate that signs the certificate. The public key in this certificate is used for signature verification and encryption.
Authorization server needs to encrypt JWTs sent to a client
Authorization server needs to sign JWTs before sending to its clients Obtain a private key for the authorization server, as well as the corresponding certificate and the CA certificate that signs the certificate. The private key is used for signing and decryption.
Authorization server needs to decrypt JWTs sent by its clients

In each case, it is also necessary to do the following on the same instance that contains the authorization server:

  • Provide trusted certificates for Caché to use. See “Providing Trusted Certificates for Caché to Use” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services. The trusted certificates must include the certificates that sign the clients’ certificates and the authorization server’s certificate (either or both, depending on which certificates you need).

  • Create a Caché credential set that enables Caché to use the certificate. See “Creating and Editing Caché Credential Sets” in the chapter “Setup and Other Common Activities” in Securing Caché Web Services.

    For the authorization server certificate, when you create the credential set, be sure to load the private key and provide the password for the private key.

  • When you configure the server, select the JWT Settings tab. On that tab, select the option Create JWT Settings from X509 credentials. Also specify the following:

    • X509 credentials — Select the credential set that uses the authorization server’s certificate and that contains the corresponding private key (for example, AuthConfig).

    • Private key password — Enter the password for the private key for this certificate.

  • When you create client definitions on the server, select the JWT Settings tab. On that tab, for Source other than dynamic registration, select X509 certificate. Also, for Client credentials — Select the credential set that uses the client’s certificate (for example, ClientConfig).