Merge pull request #8 from tnwang/develop

Upcoming documentation to support application bootstrapping. Accepted now that 1.4 tile is live.

Author: tnwang

Diff for: README.md

@@ -38,6 +38,8 @@ Set the Auth Server location as the value of the auth_domain environment variabl
 
 `cf set-env <RESOURCE_SERVER_APP_NAME> AUTH_SERVER <AUTH_SERVER_LOCATION>`
 
+For example, for a given SSO service plan/UAA identity zone, the location would be `https://subdomain.login.my-domain.org`
+
 It has three API endpoints:
  * `GET /todo` to list TODO items. Requires the user to have `todo.read` scope.
  * `POST /todo` to create a TODO item. Requires `todo.write` scope. Example body: `{"todo":"<content>"}`
@@ -61,3 +63,29 @@ Follow the steps [here](http://docs.pivotal.io/p-identity/manage-resources.html)
 The authenticated user should also have the scopes `todo.read` and `todo.write`.
 
 NOTE: If a user doesn't have these scopes, contact your local admin to grant these scopes to that user.
+
+# Bootstrap Application Client Configurations for the Pivotal Single Sign-On Service Instance
+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.
+
+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.
+
+The table below provides a description and the default values. Further details and examples are provided in the sample application manifests.
+
+| Property Name | Description | Default |
+| ------------- | ------------- | ------------- |
+| name | Name of the application | (N/A - Required Value) |
+| GRANT_TYPE | Allowed grant type for the application through the SSO service - only one grant type per application is supported by SSO | authorization_code |
+| SSO_IDENTITY_PROVIDERS | Allowed identity providers for the application through the SSO service plan | uaa |
+| 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) |
+| 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 |
+| 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> |
+| 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 |
+| SSO_REQUIRED_USER_GROUPS | Comma separated list of groups a user must have in order to authenticate successfully for the application | (No value) |
+| SSO_ACCESS_TOKEN_LIFETIME | Lifetime in seconds for the access token issued to the application by the SSO service | 43200 |
+| 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) |
+| 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) |
+| 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) |
+| 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) |
+| 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 |
+
+To remove any variables set through bootstrapping, you must use `cf unset-env <APP_NAME> <PROPERTY_NAME>` and rebind the application.

Diff for: authcode/manifest.yml

@@ -6,5 +6,42 @@ applications:
    path: build/libs/authcode.jar
    env:
      SKIP_SSL_VALIDATION: "true"
+
+     # Grant type to be set for the application's client configurations - Only one grant type per application is supported by SSO
      GRANT_TYPE: authorization_code
+
+     # Identity provider(s) to be set for the application's client configurations
      SSO_IDENTITY_PROVIDERS: uaa
+
+     # The following are bootstrap configurations you may use to automatically create client configurations in the SSO service for your application if the configurations do not exist. These configurations take effect when binding or rebinding to the SSO, and will overwrite existing client configurations if any. The values provided below are examples.
+
+     # Whitelist of redirect URI(s) allowed for the application. This value must start with http:// or https://
+     # SSO_REDIRECT_URIS: https://my-domain-here.domain.org
+
+     # Client scope(s) for the application, not used for client credentials grant type
+     # SSO_SCOPES: openid, todo.read, todo.write 
+
+     # Client scope(s) for the application that are automatically authorized when acting on behalf of a user
+     # SSO_AUTO_APPROVED_SCOPES: openid, todo.read
+
+     # Client authorities for the application, only used for client credentials grant type 
+     # SSO_AUTHORITIES: openid, uaa.resource, todo.read, todo.write
+
+     # List of groups a user must have in order to authenticate successfully for the application
+     # SSO_REQUIRED_USER_GROUPS: my_group_here
+
+     # Lifetime in seconds of the application's access token
+     # SSO_ACCESS_TOKEN_LIFETIME: 300
+
+     # Lifetime in seconds of the application's refresh token
+     # SSO_REFRESH_TOKEN_LIFETIME: 1800
+
+     # Resource(s) that the application will use as scopes/authorities to be created if they do not already exist during bootstrapping
+     # SSO_RESOURCES: |
+     #   todo.read:  Read Objects
+     #   todo.write: <Blank for no description>
+
+     # Application icon with the application name and launch URL that will be displayed on the Pivotal Account dashboard if configured to show
+     # SSO_ICON: <base64 encoded image - do not exceed 64kb>
+     # SSO_LAUNCH_URL: <url>
+     # SSO_SHOW_ON_HOME_PAGE: <true/false>

Diff for: client_credentials/manifest.yml

@@ -6,5 +6,42 @@ applications:
    path: build/libs/client_credentials.jar
    env:
      SKIP_SSL_VALIDATION: "true"
+
+     # Grant type to be set for the application's client configurations - Only one grant type per application is supported by SSO
      GRANT_TYPE: client_credentials
+
+     # Identity provider(s) to be set for the application's client configurations
      SSO_IDENTITY_PROVIDERS: uaa
+
+     # The following are bootstrap configurations you may use to automatically create client configurations in the SSO service for your application if the configurations do not exist. These configurations take effect when binding or rebinding to the SSO, and will overwrite existing client configurations if any. The values provided below are examples.
+
+     # Whitelist of redirect URI(s) allowed for the application. This value must start with http:// or https://
+     # SSO_REDIRECT_URIS: https://my-domain-here.domain.org
+
+     # Client scope(s) for the application, not used for client credentials grant type
+     # SSO_SCOPES: openid, todo.read, todo.write 
+
+     # Client scope(s) for the application that are automatically authorized when acting on behalf of a user
+     # SSO_AUTO_APPROVED_SCOPES: openid, todo.read
+
+     # Client authorities for the application, only used for client credentials grant type 
+     # SSO_AUTHORITIES: openid, uaa.resource, todo.read, todo.write
+
+     # List of groups a user must have in order to authenticate successfully for the application
+     # SSO_REQUIRED_USER_GROUPS: my_group_here
+
+     # Lifetime in seconds of the application's access token
+     # SSO_ACCESS_TOKEN_LIFETIME: 300
+
+     # Lifetime in seconds of the application's refresh token
+     # SSO_REFRESH_TOKEN_LIFETIME: 1800
+
+     # Resource(s) that the application will use as scopes/authorities to be created if they do not already exist during bootstrapping
+     # SSO_RESOURCES: |
+     #   todo.read:  Read Objects
+     #   todo.write: <Blank for no description>
+
+     # Application icon with the application name and launch URL that will be displayed on the Pivotal Account dashboard if configured to show
+     # SSO_ICON: <base64 encoded image - do not exceed 64kb>
+     # SSO_LAUNCH_URL: <url>
+     # SSO_SHOW_ON_HOME_PAGE: <true/false>

Diff for: implicit/manifest.yml

@@ -6,5 +6,42 @@ applications:
    path: build/libs/implicit.jar
    env:
      SKIP_SSL_VALIDATION: "true"
+
+     # Grant type to be set for the application's client configurations - Only one grant type per application is supported by SSO
      GRANT_TYPE: implicit
+
+     # Identity provider(s) to be set for the application's client configurations
      SSO_IDENTITY_PROVIDERS: uaa
+
+     # The following are bootstrap configurations you may use to automatically create client configurations in the SSO service for your application if the configurations do not exist. These configurations take effect when binding or rebinding to the SSO, and will overwrite existing client configurations if any. The values provided below are examples.
+
+     # Whitelist of redirect URI(s) allowed for the application. This value must start with http:// or https://
+     # SSO_REDIRECT_URIS: https://my-domain-here.domain.org
+
+     # Client scope(s) for the application, not used for client credentials grant type
+     # SSO_SCOPES: openid, todo.read, todo.write 
+
+     # Client scope(s) for the application that are automatically authorized when acting on behalf of a user
+     # SSO_AUTO_APPROVED_SCOPES: openid, todo.read
+
+     # Client authorities for the application, only used for client credentials grant type 
+     # SSO_AUTHORITIES: openid, uaa.resource, todo.read, todo.write
+
+     # List of groups a user must have in order to authenticate successfully for the application
+     # SSO_REQUIRED_USER_GROUPS: my_group_here
+
+     # Lifetime in seconds of the application's access token
+     # SSO_ACCESS_TOKEN_LIFETIME: 300
+
+     # Lifetime in seconds of the application's refresh token
+     # SSO_REFRESH_TOKEN_LIFETIME: 1800
+
+     # Resource(s) that the application will use as scopes/authorities to be created if they do not already exist during bootstrapping
+     # SSO_RESOURCES: |
+     #   todo.read:  Read Objects
+     #   todo.write: <Blank for no description>
+
+     # Application icon with the application name and launch URL that will be displayed on the Pivotal Account dashboard if configured to show
+     # SSO_ICON: <base64 encoded image - do not exceed 64kb>
+     # SSO_LAUNCH_URL: <url>
+     # SSO_SHOW_ON_HOME_PAGE: <true/false>

Diff for: password/manifest.yml

@@ -6,5 +6,42 @@ applications:
    path: build/libs/password.jar
    env:
      SKIP_SSL_VALIDATION: "true"
+
+     # Grant type to be set for the application's client configurations - Only one grant type per application is supported by SSO
      GRANT_TYPE: password
+
+     # Identity provider(s) to be set for the application's client configurations
      SSO_IDENTITY_PROVIDERS: uaa
+
+     # The following are bootstrap configurations you may use to automatically create client configurations in the SSO service for your application if the configurations do not exist. These configurations take effect when binding or rebinding to the SSO, and will overwrite existing client configurations if any. The values provided below are examples.
+
+     # Whitelist of redirect URI(s) allowed for the application. This value must start with http:// or https://
+     # SSO_REDIRECT_URIS: https://my-domain-here.domain.org
+
+     # Client scope(s) for the application, not used for client credentials grant type
+     # SSO_SCOPES: openid, todo.read, todo.write 
+
+     # Client scope(s) for the application that are automatically authorized when acting on behalf of a user
+     # SSO_AUTO_APPROVED_SCOPES: openid, todo.read
+
+     # Client authorities for the application, only used for client credentials grant type 
+     # SSO_AUTHORITIES: openid, uaa.resource, todo.read, todo.write
+
+     # List of groups a user must have in order to authenticate successfully for the application
+     # SSO_REQUIRED_USER_GROUPS: my_group_here
+
+     # Lifetime in seconds of the application's access token
+     # SSO_ACCESS_TOKEN_LIFETIME: 300
+
+     # Lifetime in seconds of the application's refresh token
+     # SSO_REFRESH_TOKEN_LIFETIME: 1800
+
+     # Resource(s) that the application will use as scopes/authorities to be created if they do not already exist during bootstrapping
+     # SSO_RESOURCES: |
+     #   todo.read:  Read Objects
+     #   todo.write: <Blank for no description>
+
+     # Application icon with the application name and launch URL that will be displayed on the Pivotal Account dashboard if configured to show
+     # SSO_ICON: <base64 encoded image - do not exceed 64kb>
+     # SSO_LAUNCH_URL: <url>
+     # SSO_SHOW_ON_HOME_PAGE: <true/false>