gistfile1.txt

# vIDM Integration with Action Cards server

ActionCards and HeroCards servers both rely on VMware Identity Manager (vIDM) to authorize
access to their API endpoints.  The ActionCards service has adopted the
[HeroCard authorization flow](https://confluence-euc.eng.vmware.com/display/AP/Hero+Card+vIDM+Authentication+Flow)
to maximize compatibility, such that the same access tokens used to call ActionCards APIs are also
passed through and used to call HeroCards APIs.  Note, however, that this is distinct from user
authentication to third-party connectors, which use their own credentials and authentication flows.

# Remote Application Clients for Development

The following remote application clients have been enabled in our VIDM instance.  Note that the Basic Auth value derives from [base64Encode(clientId + ":" + clientSecret)].

## Local development:

| | |
|-|-|
| Client ID | `ActionCards_Local` |
| Client Secret | `qRIBi5bjVj1H3WgjAQJzcknXILp7BFtiPgGbPuiCtyRQ0XFn` |
| Redirect URL | `http://localhost:8000/auth/landing_page` |

Obtain oauth tokens:
1. Start your dev server (`./bin/server`)
2. [Click to OAauth-orize](http://localhost:8000/auth/login)
3. Follow the authentication flow through vIDM
4. The "Access token" on the resulting page is your JWT and can be used to make requests

## Staging

| | |
|-|-|
| Client ID: | `ActionCards_Staging` |
| Client Secret | `u9liUCfyBu4kKZJrbqiolpujGgM8LyPTjlquh8xCQVPhcZXh` |
| Redirect URL | `https://actioncards-staging.app.socialcast.com/auth/landing_page` |

Obtain oauth tokens:
1. [Click to OAauth-orize](https://actioncards-staging.app.socialcast.com/auth/login)
2. Follow the authentication flow through vIDM
3. The "Access token" on the resulting page is your JWT and can be used to make requests

## Prototype

| | |
|-|-|
| Client ID: | `ActionCards_Prototype` |
| Client Secret: | `EZoxEVoOJtUKrgjFP1TFH50UCa2Fy5YgKI2QoWo0iwxiAU5f` |
| Redirect URL: | `https://actioncards-proto.app.socialcast.com/auth/landing_page` |

Obtain oauth tokens:
1. [Click to OAauth-orize](https://actioncards-proto.app.socialcast.com/auth/login)
2. Follow the authentication flow through vIDM
3. The "Access token" on the resulting page is your JWT and can be used to make requests

# ActionCards Development vIDM instance

Administrators can access the development vIDM instance at https://avakil.vidmpreview.com and selecting 'Administration Console' from the dropdown at the top right.

 For more information on VIDM integration in general, see:

[Single Sign On for Web Apps with VMware Identity Manager](https://github.com/vmware/idm/wiki/Integrating-Webapp-with-OAuth2)

[Single Sign-on for Mobile with VMware Identity Manager](https://github.com/vmware/idm/wiki/Single-sign-on-for-Mobile)

# Setting Up a Remote Application

Web applications authenticate to vIDM using standard [OAuth2 three-legged flow](https://malalanayake.wordpress.com/2013/01/09/3-legged-oauth-flow/). To enable the flow, the first step is for a vIDM admin to congifure a Remote Application.

1. Go to Settings.

 ![vIDM Settings](images/vidm-settings.png)

2. Go to Remote App Access.

 ![vIDM Remote Access App](images/vidm-remote-access.png)

3. Click Create Client.

 ![vIDM Create Client](images/vidm-create-client.png)

4. Select a unique Client ID, set the Redirect URL, and choose one or more permission Scope values.  Minimally select OpenID.  Note that vIDM does not currently support Applicaton or NAPPS.

 ![vIDM Add Client](images/vidm-add-client.png)

5. On the same screen, click the Advanced arrow.  Click the Generated Shared Secret link to have vIDM automatically create an OAuth2 shared secret.  You may also customize your access token and refresh token times-to-live.

 ![vIDM Add Client Advanced](images/vidm-add-client-advanced.png)

6. Click Add. Upon successful save you will see a summary screen for your new client.

 ![vIDM Client Summary](images/vidm-client-summary.png)


# Obtaining an Access Token (Details)

The example below is for the `ActionCards_Staging` client.  For other clients, change the parameters to match your desired client as per the settings described at the top of this document.

1. In a web browser, invoke the URL below.  Note that the `state` parameter should normally be a randomly generated string generated by our application, but it can also be hard-coded.  Its intended use is to prevent cross-site forgery.

* Set `response_type` to `code`
* Set `client_id` to the id of your remote application
* Set `redirect_uri` to the redirect URI configured for your remote application
* Set `state` to a random string (see note above)
* Set `scope` to desired scopes allowed for your remote application.

```
https://avakil.vidmpreview.com/SAAS/auth/oauth2/authorize?response_type=code&client_id=ActionCards_Staging&redirect_uri=https://actioncards-staging.app.socialcast.com/auth/landing_page&state=6h3qG9XkjGlfvGIee1Up2e38Cn5H0&scope=email+profile+user+openid
```

2. Click the 'Allow Access' button. You should be redirected to something like the following.

```
https://actioncards-staging.app.socialcast.com/auth/landing_page?code=Uw03kya7gEIs4BxW7oE1L6P&state=6h3qG9XkjGlfvGIee1Up2e38Cn5H0&userstore=System+Domain
```

 ![vIDM Allow Access](images/vidm-allow-access.png)

3. Extract the code parameter value from the link above and send the following command. For the Basic Auth header, use the authorization header for one of the remote applications configured above.  The following example uses staging.

* Set `grant_type` to `authorization`
* Set `code` to the code returned in step 2 above
* Set `redirect_uri` to the redirect URI configured for your remote application

```
curl -H "Authorization: Basic QWN0aW9uQ2FyZHNfU3RhZ2luZzp1OWxpVUNmeUJ1NGtLWkpyYnFpb2xwdWpHZ004THlQVGpscXVoOHhDUVZQaGNaWGg=" -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://avakil.vidmpreview.com/SAAS/auth/oauthtoken?grant_type=authorization_code&code=$(code value here)&redirect_uris=https://actioncards-staging.app.socialcast.com/auth/landing_page"
```

e.g.,

```
curl -H "Authorization: Basic QWN0aW9uQ2FyZHNfU3RhZ2luZzp1OWxpVUNmeUJ1NGtLWkpyYnFpb2xwdWpHZ004THlQVGpscXVoOHhDUVZQaGNaWGg=" -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://avakil.vidmpreview.com/SAAS/auth/oauthtoken?grant_type=authorization_code&code=Uw03kya7gEIs4BxW7oE1L6P&redirect_uri=https://actioncards-staging.app.socialcast.com/auth/landing_page"
```


4. You should get a response like the following. The access_token value is your JWT token.

```
{
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI5MGZlYWJjYy0yMzljLTQ1NjktYThiYi05N2Q5OTIxOTg4MmEiLCJwcm4iOiJtc2FhcmluZW5AQVZBS0lMIiwiZG9tYWluIjoiU3lzdGVtIERvbWFpbiIsInVzZXJfaWQiOiIxMTMzOTkiLCJhdXRoX3RpbWUiOjE1MDA2NTAyOTQsImlzcyI6Imh0dHBzOi8vYXZha2lsLnZpZG1wcmV2aWV3LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL2F2YWtpbC52aWRtcHJldmlldy5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46dm13YXJlOm5hbWVzOmFjOmNsYXNzZXM6TG9jYWxQYXNzd29yZEF1dGhcIixcImlhdFwiOjE1MDA2NDgxOTUsXCJpZFwiOjE2NTZ9XSIsInNjcCI6Im9wZW5pZCBwcm9maWxlIHVzZXIgZW1haWwiLCJpZHAiOiIwIiwiZW1sIjoibXNhYXJpbmVuQHZtd2FyZS5jb20iLCJjaWQiOiJBY3Rpb25DYXJkc19TdGFnaW5nIiwiZGlkIjoiIiwid2lkIjoiIiwiZXhwIjoxNTAwOTA5NDk0LCJpYXQiOjE1MDA2NTAyOTQsInN1YiI6ImFhNTFiNzkxLTE4OTktNDNiNC05ZGE2LTQ2OWEyNWY5MTdlYiIsInBybl90eXBlIjoiVVNFUiJ9.LPaBRXJEmzwSLvW-uq3PAR2GovYmcgcTxrA5rRMEsuczQBTBH5YiJVXYih50gPwi6zl9DckfPo7BMSSPtItpsjpLCZIgYjMtikGq7t0os1cuqEW--VLUnRz9FJW5B985q1puBji0s3u3gVlyCzqyGt8KOcxiecsEa9Vx5tpc57c",
  "token_type":"Bearer",
  "expires_in":259199,
  "refresh_token":"5MYqJMag6PoLqEgL8VkVGxK",
  "scope":"openid profile user email",
  "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InNCa0RVIn0.eyJlbWFpbCI6Im1zYWFyaW5lbkB2bXdhcmUuY29tIiwidXBkYXRlZF9hdCI6MTUwMDQwNDQyOCwiZXhwIjoxNTAwNjUwNDE0LCJpYXQiOjE1MDA2NTAyOTQsInN1YiI6Im1zYWFyaW5lbkBBVkFLSUwiLCJpc3MiOiJodHRwczovL2F2YWtpbC52aWRtcHJldmlldy5jb20vU0FBUy9hdXRoIiwiYXVkIjpbIkFjdGlvbkNhcmRzX1N0YWdpbmciXSwiYXV0aF90aW1lIjoxNTAwNjUwMjk0LCJhenAiOiJBY3Rpb25DYXJkc19TdGFnaW5nIiwiYXRfaGFzaCI6InQwY1pPUU9MSFlZQjlVSFRkbzQ0MkEiLCJnaXZlbl9uYW1lIjoiTWFyayIsImZhbWlseV9uYW1lIjoiU2FhcmluZW4iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.Ca0t7PxSCIGOEBCspdnPG6Jsh_CUGC8-D9CyUHTd1H3reMNXDjiXNWDyjLMiNmWLmKypk29Etgl-Qx-qCoxYcX0dbAmLF5fGD_gPhe7NUBBqepuZEHXEQLAzw2sPnP434zVk4gapY8JTmNNCx41CfHdNJut7gHTEjyI7xVn_7_w"
}
```