|
| 1 | +# Deploying the Authorization Code (Authcode) Sample Application |
| 2 | + |
| 3 | +The Authorization Code OAuth2 grant type is the most commonly used for web applications deployed into Cloud Foundry. |
| 4 | + |
| 5 | +This sample application integrates with the [UAA](https://github.com/cloudfoundry/uaa) using the [authorization code](https://tools.ietf.org/html/rfc6749#section-4.1) |
| 6 | +OAuth2 grant type. This sample application relies on the [Pivotal Single Sign-On Service](https://docs.pivotal.io/p-identity/1-4/index.html) |
| 7 | +to automatically register this sample application as an OAuth2 client of the UAA and the |
| 8 | +[Spring Cloud SSO Connector](https://github.com/pivotal-cf/spring-cloud-sso-connector) to automatically consume those configurations. |
| 9 | + |
| 10 | +App-specific OAuth2 client configurations are made using the environment variables section of the sample app's [`manifest.yml`](./manifest.yml) |
| 11 | +file. |
| 12 | + |
| 13 | +## Prerequisites: |
| 14 | + |
| 15 | +1. An operator must have installed the [Pivotal Single Sign-On Service](https://docs.pivotal.io/p-identity/1-4/index.html) |
| 16 | +1. An operator must have [configured at least one plan](https://docs.pivotal.io/p-identity/1-4/manage-service-plans.html) for the SSO Service that is visible to your Org. |
| 17 | +1. The person using this sample app must know login credentials for a user in this plan. For new plans, an operator may need to [create a user](http://docs.pivotal.io/p-identity/1-4/manage-users.html). |
| 18 | + |
| 19 | +### Step 0: Deploy a sample resource server |
| 20 | + |
| 21 | +The goal of applications obtaining tokens using the OAuth2 authcode grant type is to be able to use those tokens to perform privileged |
| 22 | +actions on another service fulfilling the role of a resource server. This sample authcode application is meant to obtain tokens for use with |
| 23 | +the [sample resource server application](../resource-server) which implements a simple TODO application. |
| 24 | + |
| 25 | +As a result of this relationship between the authcode client application and the resource server, having pushed a sample resource server |
| 26 | +app is a required prerequesite for working through the rest of this tutorial. [Follow these instructions](../resource-server/README.md) to |
| 27 | +deploy a sample resource server if you have not already done so. |
| 28 | + |
| 29 | +### Step 1: Update authcode manifest.yml with the location of the sample resource server |
| 30 | + |
| 31 | +The [`manifest.yml`](./manifest.yml) includes [a configuration block](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#env-block) |
| 32 | +called `env`. This section is used to list environment variables that will be available to the deployed application. |
| 33 | + |
| 34 | +In the `env` section of [`manifest.yml`](./manifest.yml), you must update the value of `RESOURCE_URL` with the location of your deployed |
| 35 | +resource server application. Replace `RESOURCE_URL: https://resource-server-sample.<your-domain>.com` with a real url. |
| 36 | + |
| 37 | +NOTE: You must leave off the trailing slash (`/`) in the `RESOURCE_URL`. |
| 38 | + |
| 39 | +### Step 2: Create an identity service instance |
| 40 | + |
| 41 | +Using the CF CLI, login as a user with the [Space Developer](https://docs.cloudfoundry.org/concepts/roles.html#roles) role and target the |
| 42 | +space where you'd like the sample app to reside. |
| 43 | + |
| 44 | + cf api api.<your-domain> |
| 45 | + cf login |
| 46 | + cf target -o <your-org> -s <your-space> |
| 47 | + |
| 48 | +All of the sample apps in this repository need to be bound to an identity service instance. If you have previously deployed one of the other |
| 49 | +sample apps, you can reuse the service instance you created at that time. See existing service instances for your space by running |
| 50 | + |
| 51 | + cf services |
| 52 | + |
| 53 | +If you don't see any service instances that have already been created for your space you will need to create a new one. To create a service |
| 54 | +instance, first list the available identity plans using |
| 55 | + |
| 56 | + cf marketplace -s p-identity |
| 57 | + |
| 58 | +Using one of the plan names from the above command, create a service instance in your space |
| 59 | + |
| 60 | + cf create-service p-identity <plan-name> p-identity-sample-instance |
| 61 | + |
| 62 | +The name of your service instance can be whatever you like, but we have chosen `p-identity-sample-instance` to match the name we have |
| 63 | +pre-specified in the [authcode sample application manifest](./manifest.yml). |
| 64 | + |
| 65 | +### Step 3: Update authcode manifest.yml with the name of your identity service instance |
| 66 | + |
| 67 | +The [`manifest.yml`](./manifest.yml) includes [a configuration block](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#services-block) |
| 68 | +called `services`. Your app will be bound to any service instances you list in this section when it is pushed. |
| 69 | + |
| 70 | +If you used the exact commands provided in Step 2, you should have a created an instance of the identity service called |
| 71 | +`p-identity-sample-instance`. Ensure this value appears in the `services` section of the `manifest.yml`. |
| 72 | + |
| 73 | +### Step 4: Deploy Sample Application to Pivotal Cloud Foundry |
| 74 | + |
| 75 | +Build the jar for our sample application: |
| 76 | + |
| 77 | + ./gradlew clean build |
| 78 | + |
| 79 | +This should result in the creation of an artifact `build/libs/authcode.jar`. Next push the authcode sample app: |
| 80 | + |
| 81 | + cf push |
| 82 | + |
| 83 | +Running `cf push` should result in |
| 84 | + |
| 85 | + - The `authcode.jar` artifact being uploaded to cloudfoundry |
| 86 | + - A public route should be bound to the sample app. `https://authcode-sample.<your-domain>/` |
| 87 | + - The app being bound to the identity service instance, which results in the creation of a new client registration for the sample app in the UAA. |
| 88 | + - The OAuth client id and client secret from the UAA are provided to your application through the `VCAP_SERVICES` environment variable. |
| 89 | + You can view these values yourself with `cf env authcode-sample`. |
| 90 | + - When the app starts, the SSO Connector reads `VCAP_SERVICES` and translates configuration from `p-identity` into the configuration needed |
| 91 | + by `org.springframework.security.oauth` to make the sample application OAuth-aware. |
| 92 | + |
| 93 | +You can verify the app is successfully running by viewing the output of `cf apps`. |
| 94 | + |
| 95 | +## Testing the TODO application |
| 96 | + |
| 97 | +You can test this sample application with users who have the `todo.read` and `todo.write` scopes for your plan. An operator can create these |
| 98 | +users with these permissions using the steps [here](https://docs.pivotal.io/p-identity/configure-id-providers.html#add-to-int). |
| 99 | + |
| 100 | +To create the resource and permissions, an operator must follow [these steps](http://docs.pivotal.io/p-identity/manage-resources.html). After |
| 101 | +the resource and permissions have been created, you need to update the authcode-sample app with the previously created scopes on the App dashboard. |
| 102 | + |
| 103 | +## Changing sample app configuration after an initial deploy |
| 104 | + |
| 105 | +To change to the SSO configuration after the deploy of the sample application, you must first manually unbind the bound identity service |
| 106 | +instance. |
| 107 | + |
| 108 | + cf unbind-service authcode-sample p-identity-service-instance |
| 109 | + |
| 110 | +After unbinding, you may change the corresponding environment variables in the `manifest.yml` before re-pushing the application. |
| 111 | + |
| 112 | +This step is needed because environment variables such as `SSO_SCOPES` are used only by the identity service broker at the time the application |
| 113 | +is bound to the service instance. These variables are consumed when the service-binding occurs during the initial app push. For more |
| 114 | +information about bootstrapping OAuth client configuration settings, please read [these docs](https://docs.pivotal.io/p-identity/1-4/configure-apps/index.html#configure). |
| 115 | + |
| 116 | +# Bootstrap Application Client Configurations for the Pivotal Single Sign-On Service Instance |
| 117 | +Beginning in SSO 1.4.0, you can use the following values your application's manifest to bootstrap client configurations for your applications automatically when binding or rebinding your application to the service instance. These values will be automatically populated to the client configurations for your application through CF environment variables. |
| 118 | + |
| 119 | +When you specify your own scopes and authorities, consider including openid for scopes on auth code, implicit, and password grant type applications, and uaa.resource for client credentials grant type applications, as these will not be provided if they are not specified. |
| 120 | + |
| 121 | +The table below provides a description and the default values. Further details and examples are provided in the sample application manifests. |
| 122 | + |
| 123 | +| Property Name | Description | Default | |
| 124 | +| ------------- | ------------- | ------------- | |
| 125 | +| name | Name of the application | (N/A - Required Value) | |
| 126 | +| GRANT_TYPE | Allowed grant type for the application through the SSO service - only one grant type per application is supported by SSO | authorization_code | |
| 127 | +| SSO_IDENTITY_PROVIDERS | Allowed identity providers for the application through the SSO service plan | uaa | |
| 128 | +| SSO_REDIRECT_URIS | Comma separated whitelist of redirection URIs allowed for the application - Each value must start with http:// or https:// | (Will always include the application route) | |
| 129 | +| SSO_SCOPES | Comma separated list of scopes that belong to the application and are registered as client scopes with the SSO service. This value is ignored for client credential grant type applications. | openid | |
| 130 | +| SSO_AUTO_APPROVED_SCOPES | Comma separated list of scopes that the application is automatically authorized when acting on behalf of users through SSO service | <Defaults to existing scopes/authorities> | |
| 131 | +| SSO_AUTHORITIES | Comma separated list of authorities that belong to the application and are registered as client authorities with the SSO service. Authorities are restricted to the space they were originally created. Privileged identity zone/plan administrator scopes (e.g. scim.read, idps.write) cannot be bootstrapped and must be assigned by zone/plan administrators. This value is ignored for any grant type other than client credentials. | uaa.resource | |
| 132 | +| SSO_REQUIRED_USER_GROUPS | Comma separated list of groups a user must have in order to authenticate successfully for the application | (No value) | |
| 133 | +| SSO_ACCESS_TOKEN_LIFETIME | Lifetime in seconds for the access token issued to the application by the SSO service | 43200 | |
| 134 | +| SSO_REFRESH_TOKEN_LIFETIME | Lifetime in seconds for the refresh token issued to the application by the SSO service | 2592000 (not used for client credentials) | |
| 135 | +| SSO_RESOURCES | Resources that the application will use as scopes/authorities for the SSO service to be created during bootstrapping if they do not already exist - The input format can be referenced in the provided sample manifest. Note that currently all permissions within the same top level permission (e.g. todo.read, todo.write) must be specified in the same application manifest. Currently you cannot specify additional permissions in the same top level permission (e.g. todo.admin) in additional application manifests.| (No value) | |
| 136 | +| SSO_ICON | Application icon that will be displayed next to the application name on the Pivotal Account dashboard if show on home page is enabled - do not exceed 64kb | (No value) | |
| 137 | +| SSO_LAUNCH_URL | Application launch URL that will be used for the application on the Pivotal Account dashboard if show on home page is enabled | (Application route) | |
| 138 | +| SSO_SHOW_ON_HOME_PAGE | If set to true, the application will appear on the Pivotal Account dashboard with the corresponding icon and launch URL| True | |
| 139 | + |
| 140 | +To remove any variables set through bootstrapping, you must use `cf unset-env <APP_NAME> <PROPERTY_NAME>` and rebind the application. |
0 commit comments