Skip to main content

Certificates and JWTs (JSON Web Tokens)

Each party in OAuth 2.0 requires public/private key pairs. For these pairs, you can use certificates and their private keys, although this is not the typical technique. This page 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.

Note:

InterSystems IRIS 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 page.

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
Either:
  • Client needs to verify signatures of JWTs sent by authorization server

  • Client needs to encrypt JWTs sent to 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.
Either:
  • Client needs to sign JWTs before sending to authorization server

  • Client needs to decrypt JWTs sent by 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.

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 InterSystems IRIS to use. 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 an InterSystems IRIS credential set that enables InterSystems IRIS to use the certificate.

    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 InterSystems IRIS to use. 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 an InterSystems IRIS credential set that enables InterSystems IRIS to use the certificate.

    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 InterSystems IRIS to use. 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 an InterSystems IRIS credential set that enables InterSystems IRIS to use the certificate.

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

FeedbackOpens in a new tab