|
2 | 2 |
|
3 | 3 | <InlineAlert slots="text"/> |
4 | 4 |
|
5 | | -The Service Account (JWT) credentials have been deprecated in favor of the OAuth Server-to-Server credentials. Your applications using the Service Account (JWT) credentials will stop working after Jun 30, 2025. You must migrate to the new credential by **Jun 30, 2025**, to ensure your application continues functioning. [Learn more](../ServerToServerAuthentication/migration.md). |
6 | | - |
7 | | -To establish a secure service-to-service Adobe I/O API session, you must create a JSON Web Token (JWT) that encapsulates the identity of your integration, and then exchange it for an access token. Every request to an Adobe service must include the access token in the `Authorization` header, along with the API Key (Client ID) that was generated when you created the [Service Account Integration](../service-account-integration.md) in the [Adobe Developer Console](https://developer.adobe.com/console/). |
8 | | - |
9 | | -## Authentication Workflow |
10 | | - |
11 | | -## Creating a JSON Web Token |
12 | | - |
13 | | -A JSON Web Token for Service Account authentication requires a particular set of claims, and must be signed using a valid digital signing certificate. We recommend that you use one of the publicly available libraries or tools for building your JWT. Examples are provided for some popular languages. |
14 | | - |
15 | | -### Required Claims for a Service Account JWT |
16 | | - |
17 | | -Your JWT must contain the following claims: |
18 | | - |
19 | | -| Claim | Description| |
20 | | -|---|---| |
21 | | -| exp | _Required_. The expiration parameter is a required parameter measuring the absolute time since 01/01/1970 GMT. You must ensure that the expiration time is later than the time of issue. After this time, the JWT is no longer valid. **Recommendation**: Have a very short lived token (a few minutes) - such that it expires soon after it has been exchanged for an IMS access token. Every time a new access token is required, one such JWT is signed and exchanged. This is secure approach. Longer lived tokens that are re-used to obtain access tokens as needed are not recommended. | |
22 | | -| iss | _Required_. The issuer, your **Organization ID** from the Adobe Developer Console integration, in the format `org_ident@AdobeOrg`. Identifies your organization that has been configured for access to the Adobe I/O API.| |
23 | | -| sub | _Required _. The subject, your **Technical Account ID ** from the Adobe Developer Console integration, in the format: `[email protected]`. | |
24 | | -| aud | _Required_. The audience for the token, your **API Key** from the Adobe Developer Console integration, in the format: `https://ims-na1.adobelogin.com/c/api_key`.| |
25 | | -| Metascopes | _Required_. The API-access claim configured for your organization: [JWT Metascopes](scopes.md), in the format: `"https://ims-na1.adobelogin.com/s/meta_scope": true`| |
26 | | - |
27 | | -The following is a sample payload to be signed and encoded. |
28 | | - |
29 | | -```json |
30 | | -{ |
31 | | - "exp": 1550001438, |
32 | | - "iss": "C74F69D7594880280.....@AdobeOrg", |
33 | | - |
34 | | - "https://ims-na1.adobelogin.com/s/ent_dataservices_sdk": true, |
35 | | - "aud": "https://ims-na1.adobelogin.com/c/a64f5f10849a410a97ffdac8ae1....." |
36 | | -} |
37 | | -``` |
38 | | - |
39 | | -### Sign and Encode your JWT |
40 | | - |
41 | | -The JWT must be signed and base-64 encoded for inclusion in the access request. The JWT libraries provide functions to perform these tasks. |
42 | | - |
43 | | -- The token must be signed using the private key for a digital signing certificate that is associated with your API key. You can associate more than one certificate with an API key. If you do so, you can use the private key of any associated certificate to sign your JWT. For more information about private key/public certificate, see [Create a public key certificate](./jwt-certificate.md#using-the-public-key-certificate-for-service-account-integration). |
44 | | - |
45 | | -**Algorithm**: **RS256** (RSA Signature with SHA-256) is an asymmetric algorithm, and it uses a public/private key pair: the identity provider has a private (secret) key used to generate the signature, and the consumer of the JWT (i.e. Adobe Developer Console) gets a public key to validate the signature. |
46 | | - |
47 | | -### Using JWT Libraries and Creation Tools |
48 | | - |
49 | | -Most modern languages have JWT libraries available. We recommend you use one of these libraries (or other JWT-compatible libraries) before trying to hand-craft the JWT. |
50 | | - |
51 | | -Other JWT tools are publicly available, such as the [JWT.IO](https://jwt.io/), a handy web-based encoder/decoder for JWTs. |
52 | | - |
53 | | -Examples are provided for several popular languages. |
54 | | - |
55 | | -| Language | Library | |
56 | | -| -------- | --------------------------- | |
57 | | -| Java | `atlassian-jwt` `jsontoken` | |
58 | | -| Node.js | `jsonwebtoken` | |
59 | | -| Python | `pyjwt` | |
60 | | - |
61 | | -### Additional JWT Libraries and Creation Tools |
62 | | - |
63 | | -The following JWT libraries are available, in addition to the Java, Node.js, and Python libraries for which we have provided examples. |
64 | | - |
65 | | -| Language | Library | |
66 | | -| -------- | ----------------------------------- | |
67 | | -| Ruby | `ruby-jwt` | |
68 | | -| PHP | `firebase php-jwt` `luciferous jwt` | |
69 | | -| .NET | `jwt` | |
70 | | -| Haskell | `haskell-jwt` | |
71 | | - |
72 | | -## Exchanging JWT to retrieve an access token |
73 | | - |
74 | | -To initiate an API session, use the JWT to obtain an access token from Adobe by making a POST request to Adobe Identity Management Service (IMS). |
75 | | - |
76 | | -- Send a POST request to: |
77 | | - |
78 | | -`https://ims-na1.adobelogin.com/ims/exchange/jwt` |
79 | | - |
80 | | -- The body of the request should contain URL-encoded parameters with your Client ID (API Key), Client Secret, and JWT: |
81 | | - |
82 | | -`client_id={api_key_value}&client_secret={client_secret_value}&jwt_token={base64_encoded_JWT}` |
83 | | - |
84 | | -### Request parameters |
85 | | - |
86 | | -Pass URL-encoded parameters in the body of your POST request: |
87 | | - |
88 | | -| Parameter | Description | |
89 | | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
90 | | -| client_id | The API key generated for your integration. | |
91 | | -| client_secret | The client secret generated for your integration. | |
92 | | -| jwt_token | A base-64 encoded JSON Web Token that encapsulates the identity of your integration, signed with a private key that corresponds to a public key certificate attached to the integration. | |
93 | | - |
94 | | -### Responses |
95 | | - |
96 | | -When a request has been understood and at least partially completed, it returns with HTTP status 200. On success, the response contains a valid access token. Pass this token in the Authorization header in all subsequent requests to an Adobe service. |
97 | | - |
98 | | -A failed request can result in a response with an HTTP status of 400 or 401 and one of the following error messages in the response body: |
99 | | - |
100 | | -|Response|Description| |
101 | | -|--- |--- | |
102 | | -|400 invalid_client|Integration does not exist. This applies both to the client_id parameter and the aud in the JWT. The client_id parameter and the aud field in the JWT do not match.| |
103 | | -|401 invalid_client|Integration does not have the exchange_jwt scope. This indicates an improper client configuration. Contact the Adobe I/O team to resolve it. The client ID and client secret combination is invalid.| |
104 | | -|400 invalid_token|JWT is missing or cannot be decoded. JWT has expired. In this case, the error_description contains more details. The exp or jti field of the JWT is not an integer.| |
105 | | -|400 invalid_signature|The JWT signature does not match any certificates attached to the integration. The signature does not match the algorithm specified in the JWT header.| |
106 | | -|400 invalid_scope|Indicates a problem with the requested scope for the token. Specific scope problems can be:Metascopes in the JWT do not match metascopes in the binding.Metascopes in the JWT do not match target client scopes.Metascopes in the JWT contain a scope or scopes that do not exist.The JWT has no metascopes.| |
107 | | -|400 bad_request|The JWT payload can be decoded and decrypted, but its contents are incorrect. This can occur when values for fields such as sub, iss, exp, or jti are not in the proper format.| |
108 | | - |
109 | | - |
110 | | -### Example |
111 | | - |
112 | | -``` |
113 | | -========================= REQUEST ========================== |
114 | | -POST https://ims-na1.adobelogin.com/ims/exchange/jwt |
115 | | --------------------------- body ---------------------------- |
116 | | -client_id={myClientId}&client_secret={myClientSecret}&jwt_token={myJSONWebToken} |
117 | | -------------------------- headers -------------------------- |
118 | | -Content-Type: application/x-www-form-urlencoded |
119 | | -Cache-Control: no-cache |
120 | | -``` |
| 5 | +As of June 30, 2025, Service Account (JWT) credentials have reached their end of life and are no longer supported. All server-to-server integrations must use the [OAuth Server-to-Server credentials](../authentication/ServerToServerAuthentication/implementation.md). View the [migration guide](../authentication/ServerToServerAuthentication/migration.md) to know more. |
0 commit comments