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
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
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
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 |