Skip to content

Commit bf39c34

Browse files
theManikJindaltheManikJindal
committed
Adding the implementation guide
1 parent 50a002b commit bf39c34

12 files changed

+471
-16
lines changed

‎src/pages/guides/authentication/AdminAuthentication/implementation.md‎

Lines changed: 174 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,191 @@
11
# Enterprise Web App credential implementation guide
22

3-
The following guide goes over finer implementation details for the Enterprise Web App credential. Before you proceed, we recommend you become familiar with [admin authentication](./index.md).
3+
The following guide goes over finer implementation details for the Enterprise Web App credential. Before you proceed, we recommend you become familiar with [admin authentication](index.md) and the [Enterprise Web App credential overview](index.md#enterprise-web-app-credential).
44

5+
## Table of contents
56

6-
---
7+
+ [Prerequisites and set up instructions](#prerequisites-and-set-up-instructions)
8+
+ [Implementing the consent worklfow](#implementing-the-consent-worklfow)
9+
+ [Step 1: Building the consent URL](#step-1-building-the-consent-url)
10+
+ [Step 2: Verifying the redirect](#step-2-verifying-the-redirect)
11+
+ [Step 3: Generating access tokens after the admin consents](#step-3-generating-access-tokens-after-the-admin-consents)
12+
+ [Rotating client secrets](#rotating-client-secrets)
13+
+ [Understanding key concepts of the Enterprise Web App Credential](#understanding-key-concepts-of-the-enterprise-web-app-credential)
14+
+ [Default redirect URI and redirect URI pattern](#default-redirect-uri-and-redirect-uri-pattern)
15+
+ [Implementing security features during the redirect](#implementing-security-features-during-the-redirect)
16+
+ [Refreshing access tokens](#refreshing-access-tokens)
17+
+ [What happens when admin revokes consent](#what-happens-when-admin-revokes-consent)
18+
+ [Testing the app before publishinig](#testing-the-app-before-publishinig)
19+
+ [Restrictions after you publish the app](#restrictions-after-you-publish-the-app)
720

821

9-
# Implementation Guide:
22+
## Prerequisites and set up instructions
1023

11-
Prerequisites and credential setup (“creating your credential”)
24+
<InlineAlert slots="text"/>
1225

13-
## The four core workflows, each with its own section:
26+
Note: You must be an Adobe Technology Partner Program (TPP) partner to use the Enterprise Web App credential.
1427

15-
Asking an admin to authorize
28+
1. If you're a developer or system admin on an Adobe Technology Partner program partner org, you can log in to the [Adobe Developer Console](https://developer.adobe.com/console/) and visit the [APIs and Services](https://developer.adobe.com/console/41528/servicesandapis) page.
1629

17-
Fetching access tokens
30+
![](../../../images/enterprise-web-app-apis-and-services.png)
1831

19-
Refreshing tokens
32+
2. Find the API or service with which you wish to integrate and click on Create Project. If the API or service supports Admin authentication, you'll see the option to select Admin authentication. If not, please reach out to your Adobe representative to log an enhancement request.
2033

21-
Admin revoking consent
34+
![](../../../images/enterprise-web-app-admin-auth.png)
2235

23-
Redirect URI and pattern deep dive
36+
// TODO fix screenshot (see left panel shows OAuth Server to Server)
37+
38+
3. Once you select Admin authentication, the Enterprise Web App credential will be automatically selected on the next screen. Here you can supply the name of your app as it will appear on the Consent screen during testing. You can change your app name later and also at the time of app submission.
2439

25-
Credential lifecycle (development, review, production)
40+
![](../../../images/enterprise-web-app-credential-name.png)
2641

27-
Best practices and security principles
42+
4. On the next screen supply the default redirect URI and redirect URL patterns your app supports for the consent workflow. You can supply `https://localhost` or `https://localhost:<port>` for local development. You can change the redirect URLs later too.
2843

44+
![](../../../images/enterprise-web-app-redirect-url.png)
2945

46+
5. On the next screen you'll be shown the scopes available to your app. Once you hit save, a project will be created for you with an Enterprise Web App credential and the selected API. You can now begin implementing the consent workflow and access token generation.
47+
48+
![](../../../images/enterprise-web-app-credential-overview.png)
49+
50+
51+
## Implementing the consent worklfow
52+
53+
### Step 1: Building the consent URL
54+
55+
The consent workflow starts when the customer admin visits the partner app and clicks on the Connect with Adobe button. You must build the consent URL and embed it in the Connect with Adobe button. Here's how -
56+
57+
1. The Adobe IMS consent screen for the Enterprise Web App credential is located at https://id.adobe.com/consent. (// TODO confirm)
58+
2. Append the query parameters `client_id`, `scope`, `state`, `nonce`, and `redirect_uri` (optional) to the above URL.
59+
1. You can find the value of `client_id` and `scope` on the Enterprise Web App credential overview page.
60+
2. You must generate cryptographically secure random strings for the value of `state` and `nonce` parameters and store these values in the user session on the backend. In order to retrieve the user's session later, you must also store the user's session ID in the browser (cookies or local storage).
61+
3. You can optionally specify a `redirect_uri` in the consent URL to redirect the admin to a URL different from your default redirect URI. The supplied URL must match one of the redirect URL patterns configured in the credential.
62+
3. Embed the consent URL in the Connect with Adobe button for the admin to click.
63+
64+
### Step 2: Verifying the redirect
65+
66+
Once the admin provides consent and is redirected back to your app, a few query parameters will be appended to the redirect URL containing information on whether the admin consented to your app or not. The query parameters will also contain information critical to verifying the legitmacy of the redirect.
67+
68+
1. The `admin_consent` parameter is set to `true` if the admin provided consent to your application, and `false` if the admin cancelled the workflow. The `admin_consent` parameter will not be present in the redirect in cases of error. Instead the `error` parameter will be present and the error code will be supplied as the value. Look at the [API reference](ims.md#) (// TODO link to exact section) to view all error codes and what they mean.
69+
70+
2. The `state` query parameter will be appended to the redirect URL if you specified it in the consent URL. The `state` parameter is used to prevent Cross-site Request Forgery (CSRF) attacks. To validate it, you must send the `state` parameter and the user's session ID (stored in browser cookies or local storage) to your backend server. Your backend server must match the value of the `state` parameter in the redirect to the one stored in the user's session on your backend server. If the values do not match, you must terminate the consent workflow and not trust the redirect.
71+
72+
3. The `id_token` parameter is only present if the admin provided consent to your application. To validate it, you must send the `id_token` parameter and the user's session ID (stored in browser cookies or local storage) to your backend server. Your backend server must -
73+
1. Inspect the `id_token` and validate its signature (view sample code here).
74+
2. Inspect the `id_token` and extract the value of the `nonce` claim from the token (view sample code here). Match the value of the `nonce` claim to what is stored in the user's session on your backend server. If the values do not match, terminate the consent workflow.
75+
3. If the singature of the `id_token` is not valid or the value of the `nonce` claim doe not match, you must terminate the consent worklow and not trust the redirect.
76+
77+
<InlineAlert slots="text"/>
78+
79+
Verifying the redirect is critical to the security of your application and Adobe customer data. View our [code samples](samples.md) (available in NodeJS, Python, and Java) to learn how to implement the verification logic in your application.
80+
81+
82+
### Step 3: Generating access tokens after the admin consents
83+
84+
Once you have verified the redirect, you are ready to generate access tokens. Now, you can store the mapping of the customer account in your identity to the customer's Adobe org ID.
85+
86+
<InlineAlert slots="text"/>
87+
88+
While the Adobe customer org ID is easily available through other means, you must never trust an org_id value which was not extracted from a valid `id_token` received in the redirect. This attack vector can be exploited by a malicious customer to link their account to another customer's org and exchange data.
89+
90+
91+
The customer `org_id` can be extracted from the `id_token` by inspecting it. The value of the `org_id`, along with your `client_id`, `client_secret`, and `scopes` can be used to then generate access tokens on behalf of the customer.
92+
93+
The following cURL command generates access tokens for the technical account set up in the customer org. The HTTP response for the cURL request contains
94+
1. The `access_token` you can use to call Adobe APIs on the customer's behalf.
95+
2. The `expires_in` value in seconds that determines how soon the access token will expire.
96+
97+
```cURL
98+
curl -X POST 'https://ims-na1.adobelogin.com/ims/token/v3'
99+
-H 'Content-Type: application/x-www-form-urlencoded'
100+
-d 'grant_type=client_credentials&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&scope=<COMMA_SEPARATED_SCOPES>'
101+
```
102+
103+
Sample response
104+
```JSON
105+
{
106+
"access_token": "ey.....",
107+
"expires_in": 3599
108+
}
109+
```
110+
111+
## Rotating client secrets
112+
113+
Rotating client secrets periodically is recommended because your application will deal with Adobe customer data. Furthermore, you must rotate your client secret immediately if you believe it has been compromised.
114+
115+
Client secret for the Enterprise Web App credential can be rotated through the Dev Console UI. To rotate client secrets through the UI, follow the steps below on the Enterprise Web App credential overview screen -
116+
117+
1. Add a new client secret to your credential.
118+
119+
![](../../../images/enterprise-web-app-client-secret.png)
120+
![](../../../images/enterprise-web-app-client-secret-add.png)
121+
122+
123+
1. Update your application to replace your old client secret with the new one you added.
124+
2. Check the client secret last used timestamp to make sure your application is no longer using the old client secret.
125+
3. Once sure that you have successfully replaced the client secret, you can delete the old client secret.
126+
127+
![](../../../images/enterprise-web-app-client-secret-delete.png)
128+
129+
<InlineAlert slots="text"/>
130+
131+
Once a client secret is deleted, you cannot restore it. So be extra sure you have replaced the old client secret with the new one in all locations.
132+
133+
### Rotating client secrets programmatically
134+
Unfortunately, rotating client secrets programmatically for the Enterprise Web App credential is currently not possible.
135+
136+
## Understanding key concepts of the Enterprise Web App Credential
137+
138+
### Default redirect URI and redirect URI pattern
139+
140+
Once the consent screen loads the admin can provide consent to your app or cancel the workflow. In either case and even in cases of error, the admin will be redirected back to your application.
141+
142+
If a `redirect_uri` was not specified in the consent URL or in cases of error, Adobe will redirect the admin to the default redirect URI configured in your credential. The default redirect URI can be up to 256 characters. It must be a `https` URL and absolute URL without wildcards. For example: `https://localhost`, `https://localhost:8000`, `https://example.com/redirect`.
143+
144+
However, if a `redirect_uri` was specified in the consent URL and matches one of the redirect URL patterns configured in your credential, Adobe will redirect the admin to the specified redirect URL.
145+
146+
The redirect URL pattern is a comma-separated list of URI path regexs used to validate any `redirect_uri` you request in the consent URL. The redirect URL pattern can be up to 512 characters. It must contain `https` URLs and supports wildcards to club multiple redirect URLs together. As each redirect URI pattern is treated as a regex, you must escape periods in the redirect URL patterns (**.**) with **\\**. Also for security reasons, wildcards are not allowed in subdomains or HTTP port, they're only allowed in the HTTP path. For example: `https://example\\.com/redirect/*`.
147+
148+
### Implementing security features during the redirect
149+
150+
Once the admin provides consent and is redirected back to your app, you must verify that the redirect is legitimate and triggered by Adobe.
151+
152+
1. Read the section on Implementing the consent workflow, especially [Step 2: Verifying the redirect](#step-2-verifying-the-redirect) to understand verification steps in detail.
153+
2. View the [sample code](samples.md) available in NodeJS, Python, and Java to implement the verification logic in your application.
154+
3. Ensure the verification logic is implemented in the backend server.
155+
156+
157+
### Refreshing access tokens
158+
159+
The Enterprise Web App credential enables partner apps to generate access tokens, however, no refresh tokens are generated. This is because the partner app can use its `client_id`, `client_secret`, `scope`, and the customer `org_id` at any time to generate another access token. Refresh tokens are simply not required.
160+
161+
### What happens when admin revokes consent
162+
163+
As soon as a customer admin revokes consent, the partner app can no longer generate access tokens on behalf of that customer. Furthermore, the technical account which was created in the customer org during the consent is also deleted.
164+
165+
Note: any existing access tokens may continue to work for up to an hour. However, since the technical account is deleted, they may not be of much use. The partner app will cease to have any access to the customer data within an hour of the admin revoking the consent.
166+
167+
### Testing the app before publishinig
168+
169+
After you have created a Project on the Developer Console and set up an Enterprise Web App credential, you can add a Test technical account to the credential.
170+
171+
Usually when a customer installs a partner built app, the partner owns the credential and the customer owns the technical account. However, for testing, the partner can "install" the app in their own organization and a test technical account will be created.
172+
173+
There are multiple ways to create a test technical account -
174+
1. Click on the Generate access token for testing button on the Enterprise Web App Credential overview page.
175+
2. Use the credential playground - Learn how to generate access tokens tab on the Enterprise Web App Credential overview page.
176+
3. Provide consent to your own application by triggering the consent workflow out of band.
177+
178+
Once a test technical account is set up, you can assign product profiles to it by visiting the Test technical account tab on the Enterprise Web App Credential overview page.
179+
180+
Note: Adding or removing product profiles to the test technical account has no effect on the product profiles customer admins assign to technical accounts in their org. Furthermore, removing the test technical account from the Enterprise Web App credential does not affect any technical accounts on customer orgs that were created when the customer admin consented to your app.
181+
182+
### Restrictions after you publish the app
183+
184+
During development, Adobe does not allow customers to consent to your app since their data can be at risk. Adobe only allows customers to consent to apps that are reviewed by Adobe and are now in production.
185+
186+
So, once you finish developing your app and are ready to publish, you must fill out listing details and submit the app for Adobe review. See our [submission guide](https://www.adobe.com/go/dd_ExperienceCloud_Submissions) for instructions.
187+
188+
After you submit the app for review or once it is published, a few restrictions are applied to the Enterprise Web app credential in the Project.
189+
190+
1. You cannot add or remove APIs connected to the Enterprise Web App credential.
191+
2. You cannot remove the Adobe Exchange redirect URL pattern added to the list of patterns.

‎src/pages/guides/authentication/AdminAuthentication/index.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ Note: Admin authentication and the Enterprise Web App credential is only availab
1111

1212
Admin authentication enables partner-built apps to read and modify Adobe enterprise customer data. Previously, enterprise customer data could only be manipulated through server to server authentication. Therefore, a customer had to build the app themsleves or plug in their server-to-server credentials in partner-built apps.
1313

14-
With Admin authentication a partner application can now have a single set of credentials and multiple customers could install the app easily by providing consent to it. The customer no longer needs to supply their credentials to partner apps, thereby, strenghting their security posture.
14+
With Admin authentication a partner application can have a single credential and multiple customers can install the app. The customer no longer needs to supply their credentials to partner apps, thereby, strenghting their security posture. Furthermore, the partner apps built with Admin authentication are click-to-install apps which can be installed without the help of an IT department on the customer organization.
1515

16-
To better understand the differences and similarities of admin authenticaton, let's compare it to other supported authentication types.
16+
To better understand the nuances of admin authentication, let's compare it to other supported authentication types.
1717

1818
| | Who builds the app? | What data can the app access? | How is data access governed? |
1919
|---------------------------------|----------------------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -52,5 +52,4 @@ Note: The customer admin can visit the [Adobe Exchange manage page](https://exch
5252

5353
1. Read the [implementation guide](implementation.md) to start implementing the Enterprise Web App credential.
5454
2. Read the [API Reference](ims.md) to view the HTTP request to generate access tokens and supported query parameters and error codes in redirect.
55-
3. Visit the [FAQ page](faq.md) for conceptual questions, troubleshooting your app, and advanced scenarios.
56-
4. Read our [submission guide](TODO) to submit you app for Adobe review.
55+
3. Read the [submission guide](https://www.adobe.com/go/dd_ExperienceCloud_Submissions) to submit you app for Adobe review.

0 commit comments

Comments
 (0)