Only authenticated users can access RMS resources. RMS API authentication supports 2 methods:
1. API Key Authentication
API Key Authentication is a simple method for clients to authenticate themselves to the RMS API. This method involves including a unique API key in the request to verify the client's identity.
Method: RMS assigns a unique key to each client accessing the API
Required User Actions:
Step 1: Include your API key as part of the request to authenticate yourself
POST https://{{apiEndpoint}}/auth/token
{
"subscriptionId": "{{subscriptionId}}",
"apiKey": "{{rmsApiKey}}"
}
subscriptionId - the value that you can locate in the RMS Console > API Access > "AZURE_SUBSCRIPTION_ID"
apiKey - the value that you can locate in the RMS Console > API Access > Api Key
The subscriptionId ensures that the request is associated with the correct RMS account, while the apiKey authenticates the specific client making the request.
Step 2: Obtain a generated token. Upon successful authentication, a token will be generated and returned in the response.
RMS supports manual API key revocation (rotation). The client can request a new API key making the previous one automatically invalid. This feature is beneficial in case a key is compromised, allowing the server to revoke the key.
JWT token Bearer Authentication
JWT (JSON Web Token) Token Bearer Authentication is a secure method that involves issuing an access token after the user has authenticated. This token is then used to authorize all subsequent requests.
Method: RMS grants an access token to verify the user’s identity
Required User Actions:
Step 3: Include the obtained token into the request header to make it authorized
Example request
GET /api/media/{id}
...
Authentication: Bearer {bearer-token}
...
<BODY>
Limited session length
Session length is the time a user spends on a website in one session. In the context of RMS, it is limited using the token's expiration, EXP parameter. The session length is set to 1 hour and cannot be modified.
2. Asymmetric Key Token Authentication with X.509 Certificates
This method uses an asymmetric key pair (public and private keys) for authentication and signing JWT tokens. The process involves generating an X.509 certificate and using it for secure communication between the client and the RMS service.
Method: Uses an asymmetric key pair (public and private keys) for authentication and signing. The X.509 certificates include both within it.
Required User Actions:
Step 1: Generate X.509 Certificate using openssl.
openssl req -x509 -sha256 -nodes -newkey rsa:2048 -days 365 -subj '/CN=localhost' -out cert.pem -keyout key.pem
The private key is stored securely by the user, often in a certificate registry, while the X.509 certificate is used for signing JWT tokens and verifying their authenticity. Learn more:
Authenticate with X.509 certificates - Azure IoT Hub
Best Practices for Storing X.509 Private Keys
Step 2: Generate JWT Token
Create a JWT token using the private key, including necessary claims.
{
"alg": "RS256",
"kid": "your_key_id",
"x5t": "your_cert_thumbprint",
"typ": "JWT"
}
alg - The algorithm used for signing the token.
kid - Key ID.
x5t - X.509 thumbprint.
Step 3: Include the obtained token into the request header to make it authorized
Example
GET /your/api/endpoint HTTP/1.1
...
Host: your.api.host
Authorization: Bearer {your_jwt_token}
...
<BODY>
The RMS service verifies the signature of the JWT token using the public key extracted from the X.509 certificate.
When the token expires, the user repeats the process to generate a new JWT token.