Introduction

SSO Tile provides a Plan API for managing SSO Plans via https://sso-api.YOUR-SYSTEM-DOMAIN. System operators can use the Plan API to automate plan creation, retrieval, update, and deletion.

Authentication

SSO Plan API uses an OAuth2 access token to access the API. An access token capable of using all the Plans API, can be created with one of the following scope combinations:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Base scopes	`cloud_controller.admin` `zones.write` `scim.write` `scim.read`

For all API calls, you must include Authorization: Bearer YOUR_ACCESS_TOKEN as a request header. For example, to get all plans,

curl "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Creating an Automation Client

$ uaac client add example-sso-client --secret sso-client-secret --authorized_grant_type client_credentials --authorities "cloud_controller.admin,zones.write,scim.write,scim.read"

On the right, we show how to create a client using uaac client add. Please see the scopes required per endpoint to determine the appropriate authorities to give to your client.

To create clients you must do so with a user or client containing any of the following scope combinations:

Scenario	Scopes Required
UAA Admin	`uaa.admin`
Zones UAA Admin	`zones.uaa.admin`
Base scopes	`clients.read` `clients.write`

You may also create a client directly from UAA using their API. Please see: Clients > Create

Acquiring an access token

# Using UAA CLI with UAA User
$ uaac target login.YOUR-SYSTEM-DOMAIN
$ uaac token owner get CLIENT_ID USERNAME -p PASSWORD -s CLIENT_SECRET
# Note: You must create your own client that allows the scopes required
$ uaac context

# Using CF CLI with UAA Client
$ cf api api.YOUR-SYSTEM-DOMAIN
$ cf auth CLIENT_ID CLIENT_SECRET --client-credentials
$ cf oauth-token

# Using UAA CLI with UAA Client
$ uaac target login.YOUR-SYSTEM-DOMAIN
$ uaac token client get CLIENT_ID -s CLIENT_SECRET
$ uaac context

Access tokens may be retrieved in many ways. On the right, we show common approaches to authenticating against the appropriate UAA and retrieving an access token. For command line usage, it is helpful to extract the token into an environment variable, such as $SSO_TOKEN.

You may also fetch a token directly from UAA using their API. Please see the supported grant types: Token

Workflows

Managing CloudFoundry Organizations for SSO Plans

$ cf api api.cf.example.com
Setting api endpoint to api.cf.example.com...

$ cf auth sso-api-client sso-api-client-secret --client-credentials
API endpoint: https://api.cf.example.com
Authenticating...
OK
Use 'cf target' to view or set your target org and space.

$ cf service-access -e p-identity
Getting service access for service p-identity as ...
broker: identity-service-broker
   service      plan                 access    orgs
   p-identity   uaa                  none
   p-identity   example-all     all
   p-identity   example                 limited   org1,org2

$ cf enable-service-access p-identity -p example -o system
Enabling access to plan asdf of service p-identity for org system as ...
OK

$ cf enable-service-access p-identity -p example-all
Enabling access of plan some-auth-domain for service p-identity as ...
OK

$ cf disable-service-access p-identity -p example
Disabling access of plan example for service p-identity as ...
OK

$ cf disable-service-access p-identity -p example-all
Disabling access of plan example-all for service p-identity as ...
OK

In order to manage CloudFoundry Organizations for SSO Plans, we will be using the CF cli: https://github.com/cloudfoundry/cli.

Please target and authenticate using the CF cli prior to running the following commands. You may authenticate using cf login or cf auth. cf auth is useful when authenticating as a service account. These commands require a user with the cloud_controller.admin scope.

Plan names are derived from the SSO Plan's auth domain. This can be retrieved in the response for Creating a Plan or Getting a Plan by ID.

Viewing current plan access to orgs

cf service-access -e p-identity

Give plan access to a specific org

cf enable-service-access p-identity -p PLAN_AUTH_DOMAIN -o ORG_NAME

Give plan access to all orgs

cf enable-service-access p-identity -p PLAN_AUTH_DOMAIN

Remove plan access from a specific org

cf disable-service-access p-identity -p PLAN_AUTH_DOMAIN -o ORG_NAME

Remove plan access from all orgs

cf disable-service-access p-identity -p PLAN_AUTH_DOMAIN

Managing Plan Administrators for SSO Plans

$ uaac target login.cf.example.com

Target: https://login.cf.example.com
Context: admin, from client admin

$ uaac token client get sso-api-client -s sso-api-client-secret

Successfully fetched token via client credentials grant.
Target: https://login.cf.example.com
Context: sso-api-client, from client sso-api-client

$ uaac group get zones.7891c78f-0cbd-46ab-9205-ef6f945c8071.admin
  id: a89ff489-f910-42e9-a8fc-a40486bb5b7f
  meta
    version: 4
    created: 2018-10-30T23:09:58.000Z
    lastmodified: 2018-11-26T22:38:37.000Z
  description:
  members:
  -
    origin: uaa
    type: USER
    value: 5d09d594-546d-49fd-b8c1-986875d2b45c
  -
    origin: uaa
    type: USER
    value: 9ceb2a21-e7ca-428d-ad51-3cb5df9919fe
  schemas: urn:scim:schemas:core:1.0
  displayname: zones.7891c78f-0cbd-46ab-9205-ef6f945c8071.admin
  zoneid: uaa

$ uaac curl /Users?filter=id+eq+%225d09d594-546d-49fd-b8c1-986875d2b45c%22
{
  "resources": [
    {
      "id": "5d09d594-546d-49fd-b8c1-986875d2b45c",
      "userName": "plan-admin",
      ...
    }
  ]
}

$ uaac member add zones.7891c78f-0cbd-46ab-9205-ef6f945c8071.admin my-plan-administrator
success

$ uaac member delete zones.7891c78f-0cbd-46ab-9205-ef6f945c8071.admin my-plan-administrator
success

In order to manage Plan Administrators for SSO Plans, we will be using the UAA cli: https://github.com/cloudfoundry/cf-uaac.

Please target and authenticate the system UAA zone using the UAA cli prior to running the following commands. The UAA cli has many ways of fetching a token, please see uaac token --help for options.

For these commands, you will need to know the Plan ID. This can be retrieved in the response for Creating a Plan or Listing Plans.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`uaa.admin`
Zones UAA Admin	`zones.uaa.admin`
Base scopes	`scim.read` `scim.write`

Create UAA group

The zones.PLAN_ID.admin group may not exist in UAA. You can run the following:

uaac group add zones.PLAN_ID.admin

This command may error if the group already exists, you can safely ignore the error if so.

Viewing current plan administrators for a plan

uaac group get zones.PLAN_ID.admin

The response will list plan administrators by the user ID. To view more information about the users in the response, you may use the UAA List Users API.

Grant a plan administrator access to a plan

uaac member add zones.PLAN_ID.admin [usernames...]

Revoke a plan administrator access to a plan

uaac member delete zones.PLAN_ID.admin [usernames...]

Plans

The Plan Object

{
  "id": "1",
  "name": "some-plan-name",
  "description": "some-description",
  "auth_domain": "some-auth-domain",
  "instance_name": "some-instance-name"
}

Field	Type	Unique	Description
id	String	true	ID of the plan
name	String		Name of the plan
description	String		Appears as a plan feature in the Services Marketplace
auth_domain	String	true	Subdomain of the URL where users authenticate to access applications covered by the service plan
instance_name	String		Appears on the login page and in other user-facing content, such as email communications

Create a Plan

Example Request:

curl -X POST "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans" \
  -H "Authorization: Bearer some-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "some-plan-name",
    "description": "some-description",
    "auth_domain": "some-auth-domain",
    "instance_name": "some-instance-name"
  }'

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "1",
  "name": "some-plan-name",
  "description": "some-description",
  "auth_domain": "some-auth-domain",
  "instance_name": "some-instance-name"
}

This endpoint creates a plan.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Zone writer	`cloud_controller.admin` `zones.write`

HTTP Request

POST /v1/plans

Request Body Fields

Field	Type	Description
name	String	Name of the plan
description	String	Appears as a plan feature in the Services Marketplace
auth_domain	String	Subdomain of the URL where users authenticate to access applications covered by the service plan
instance_name	String	Appears on the login page and in other user-facing content, such as email communications

Response Body

Plan Object

Get a Plan by ID

Example Request:

curl "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans/1" \
  -H "Authorization: Bearer some-token"

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1",
  "name": "some-plan-name",
  "description": "some-description",
  "auth_domain": "some-auth-domain",
  "instance_name": "some-instance-name"
}

This endpoint retrieves a plan by its ID.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Zone writer	`cloud_controller.admin` `zones.write`
Zone reader	`cloud_controller.admin` `zones.read`

HTTP Request

GET /v1/plans/{id}

Request Parameters

Parameter	Type	Description
id	String	ID of the plan, which is included in the response of the Create a Plan endpoint.

Response Body

Plan Object

Update a Plan by ID

Example Request:

curl -X PATCH "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans/1" \
  -H "Authorization: Bearer some-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-plan-name",
    "description": "new-description",
    "instance_name": "new-instance-name"
  }'

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1",
  "name": "new-plan-name",
  "description": "new-description",
  "auth_domain": "old-auth-domain",
  "instance_name": "new-instance-name"
}

This endpoint updates a plan.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Zone writer	`cloud_controller.admin` `zones.write`

HTTP Request

PATCH /v1/plans/{id}

Request Parameters

Parameter	Type	Description
id	String	ID of the plan, which is included in the response of the Create a Plan endpoint.

Request Body Fields

One or more of the following fields is required:

Field	Type	Description
name	String	Name of the plan
description	String	Appears as a plan feature in the Services Marketplace
instance_name	String	Appears on the login page and in other user-facing content, such as email communications

Note: A plan's auth domain is immutable.

Response Body

Plan Object

Delete a Plan by ID

Example Request:

curl -X DELETE "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans/1" \
  -H "Authorization: Bearer some-token"

Example Response:

HTTP/1.1 204 No Content
Content-Type: application/json

This endpoint deletes a plan by its ID.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Zone writer	`cloud_controller.admin` `zones.write`

HTTP Request

DELETE /v1/plans/{id}

Request Parameters

Parameter	Type	Description
id	String	ID of the plan, which is included in the response of the Create a Plan endpoint.

List all Plans

Example Request:

curl -X GET "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans" \
  -H "Authorization: Bearer some-token"

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "plans": [
    {
      "id": "1",
      "name": "some-plan-name",
      "description": "some-description",
      "auth_domain": "some-auth-domain",
      "instance_name": "some-instance-name"
    },
    {
      "id": "2",
      "name": "some-other-plan-name",
      "description": "some-other-description",
      "auth_domain": "some-other-auth-domain",
      "instance_name": "some-other-instance-name"
    }
  ]
}

This endpoint lists all plans.

Required Scopes

One of the following combinations of scopes is required:

Scenario	Scopes Required
UAA Admin	`cloud_controller.admin` `uaa.admin`
Zones UAA Admin	`cloud_controller.admin` `zones.uaa.admin`
Zone writer	`cloud_controller.admin` `zones.write`
Zone reader	`cloud_controller.admin` `zones.read`

HTTP Request

GET /v1/plans

Response Body

Plan Object array

Status Codes

The SSO API uses the following status codes:

Code	Status	Description
200	OK	Successfully retrieved or updated SSO plan(s)
201	Created	Successfully created an SSO plan
204	No Content	Successfully deleted an SSO plan
400	Bad Request	Request body is malformed
401	Unauthorized	Invalid or missing access token
403	Forbidden	Missing required scopes for a requested operation
404	Not Found	Failed to find the requested SSO plan
500	Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request