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.

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.

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

# generate corresponding public key
# Enter the maximum number of days the cerficate if valid for in MAX CERT AGE
openssl req -new -x509 -key privatekey.pem -out pubcert.pem -days <MAX_CERT_AGE>

# 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

This will generate a public/private key pair (one file with the private key and a another one with the public key).

In MacOS/Linux, you can use the following command to copy the contents of the certificates for the next steps:

pbcopy < filename.pem

Alternatively, you can use an online RSA Generator.

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.
• Click on Set scopes if you'd like to restrict the permissions for this specific key (Optional). By default all scopes will be selected.
• Copy the contents of the public key that was generated before into the Public key field 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 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. Select JWT encoder.
3. At the top of the page select algorithm: RS256.
4. Copy and paste the following in the payload section:

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

/**
 * iss: enter the client ID from the UI
 * sub: enter the client ID from the UI
 * 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. Once filled in, remove the comment section
5. 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.
6. It is also possible to verify that the public key is valid by adding public key contents to the public key box.
7. 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.

🚧

Authorization token validity

Once generated, the authorization token has a validity of 24 hours.