OAuth2.0 authentication

Use OAuth 2.0 authentication for the Xtremepush External API, so that you can create, manage and delete tokens independently for different connections. Only private key-based authentication is allowed.

Public/Private Key

You will need to create an RSA public/private key pair to generate JWT tokens. Your private key is not stored in our system.

Add new public key

• Navigate to Settings > Integrations > API Integration > Add Client ID.
• Enter a custom name for the new key as an internal reference and press the Save 💾 button.
• Use the generated Client ID as <UNIQUE_KEY_IDENTIFIER> in the next steps to generate keys and JWT tokens.
• Once you have generated an RSA key and a certificate you can upload the public certificate by pressing Add Key and pasting the contents of the file and then pressing Add to verify and store it.

It is possible to delete tokens from this same page by clicking on each token's Options menu > Delete

Generate RSA key

This section describes the methods that can be used to create RSA keys using a command line interface tool (for example PowerShell on Windows or Terminal on MacOS), but there are other methods available.

# This command will ask for additional information. In the last step type `yes` and press Enter
keytool -genkey -alias <UNIQUE_KEY_IDENTIFIER> -keyalg RSA -keysize 2048 -validity <MAX_CERT_AGE> -keystore xtremepush.jks

# Import keys from the KeyStore
keytool -importkeystore -srckeystore xtremepush.jks -destkeystore xtremepush.p12 -deststoretype PKCS12

# Export the public and private keys
openssl pkcs12 -in xtremepush.p12 -nokeys -out pubcert.pem
openssl pkcs12 -in xtremepush.p12 -nodes -nocerts -out privatekey.pem

# generate a private key with the correct length
openssl genrsa -out privatekey.pem 2048

# generate corresponding public key
# This command will ask you for additional information
openssl req -new -x509 -key privatekey.pem -out pubcert.pem -days <MAX_CERT_AGE>

You can use an online RSA Generator.

Generate a JWT token

To create a JWT token you will need a token generator, for testing purposes an example will be shown below.

1. Open up the JWT generator tool .
2. At the top of the page select algorithm: RS256.
3. Copy and paste the following in the payload section:

{
    "iss": "<UNIQUE_KEY_IDENTIFIER>",
    "sub": "<UNIQUE_KEY_IDENTIFIER>",
    "exp": 1541054464,
    "iat": 1521054464,
    "jti": "nonce1234"
}

/**
 * iss: use the same value that was used to create the public/private keys
 * sub: use the same value that was used to create the public/private keys
 * exp: expiration timestamp (epoch), keep short as auth tokens can not be revoked once issued
 * iat: This is the time when this JWT was created (epoch)
 * jti: set to a unique identifier for the JWT (optional)
 */

4. Copy the contents of the private key that was created earlier (only the part that begins and ends with "-----") and put it in the private key box in the Verify Signature section.
5. It is also possible to verify that the public key is valid by adding public key contents to the public key box.
6. Copy the JWT token that was generated.

Exchange JWT token for Authorization token

You can obtain the Xtremepush authorization token by making a REST API call to the /api/oauth/token endpoint. Make sure to add the following header to the request:

Authorization: Bearer <jwt_token>

Add the Authorization: Bearer <authorization_token> header when attempting to make REST API calls to Xtremepush's External API.