Introduction to our Custom Keystone API Extension

We have created a custom extension for Keystone which allows for self-service (formerly known as "token tenant"). Our clients may interface directly with this extension; one use case for this extension is for integration with client-created portals. This extension is called the Keystone MCAPI.

This introduction is intended for our clients' developers, to provide familiarity with the additional functionality the Keystone MCAPI provides. Please note that the term "project" below refers to the concept formerly known as "tenant". If you have an admin context on your Keystone token, there are no restrictions on what calls you can perform.  Certain calls require cloud admin context; they are noted below. Anyone making these calls against the Keystone MCAPI Extension will require a Keystone authorization token.

The following calls are intended to be accessed via the public port to Keystone on the Keystone API host in a particular availability zone.  Their results are provided in JSON format. Each of these requests are made to the Keystone endpoint (e.g. http://<keystone-api-host>:35357/v2.0/<MCAPI API CALL>).

 

HTTP Method: GET

/MCAPI/services/projects/authorized

List all authorized self-service projects within an availability zone. 

If self-service is enabled for a project, and you are a member of that project, the project is in the authorized list for your user.

Example Output

{
    "authorized_projects": [
        {
            "description": "Test Project 1",
            "domain_id": "default",
            "enabled": true,
            "id": "<project_uuid>",
            "name": "Test Project 1",
            "self_service_managers": [
                "<first_project_self-service_manager_user_uuid>",
                "<second_project_self-service_manager_user_uuid>"
            ],
            "self_service_token": "<invite_token>"
        },
		{
            "description": "Test Project 2",
            "domain_id": "default",
            "enabled": true,
            "id": "<project_uuid>",
            "name": "Test Project 2",
            "self_service_managers": [
                "<first_project_self-service_manager_user_uuid>",
                "<second_project_self-service_manager_user_uuid>"
            ],
            "self_service_token": "<invite_token>"
        }
    ]
}

/MCAPI/services/projects/available

List all available self-service projects within an availability zone.

If self-service is enabled for a project, and you are not a member of that project, the project is in the available list for your user.

Example Output

{
    "available_projects": [
        {
            "description": "Third Test Project", 
            "enabled": true, 
            "id": "<project_uuid>", 
            "name": "Test Project 3", 
            "self_service_managers": [
                "<first_project_self-service_manager_user_email_address>",
                "<second_project_self-service_manager_user_email_address>"
            ]
        },
        {
            "description": "Fourth Test Project", 
            "enabled": true, 
            "id": "<project_uuid>", 
            "name": "Test Project 4", 
            "self_service_managers": [
                "<first_project_self-service_manager_user_email_address>",
                "<second_project_self-service_manager_user_email_address>"
            ]
        }
    ]
}

/MCAPI/services/project/{project_uuid} 

Members of a specific self-service-enabled project may get information about that specific project.

Example Output

{
    "project": {
        "description": "First Test Project", 
        "domain_id": "default", 
        "enabled": true, 
        "id": "<project_uuid>", 
        "name": "Test Project", 
        "self_service_managers": [
                "<first_project_self-service_manager_user_uuid>",
                "<second_project_self-service_manager_user_uuid>"
        ], 
        "self_service_token": "<invite_token>"
    }
}

/MCAPI/services/project/{project_uuid}/users 

Members of a specific self-service-enabled project may get a list of all users who are members of that specific project.

Example Output

{
    "users": [
        {
            "email": "<first_project_user_email_address>", 
            "id": "<first_project_user_uuid>", 
            "name": "<first_project_user_username>"
        },
        {
            "email": "<second_project_user_email_address>", 
            "id": "<second_project_user_uuid>", 
            "name": "<second_project_user_username>"
        }
    ]
}

/MCAPI/services

This is publicly-accessible data to anyone who can make a request to the API.  The fields available via this call are as follows:

  • member_role_name - this is internal Keystone data, and not relevant
  • project_misc_fields - a list of additional client-specific custom fields for projects, defined by our clients (example BillingCategory, Division)
  • self_service_create_project - Boolean value, if True then new self-service projects may be created by any valid user
  • self_service_join_project - Boolean value, if True then user may use invite tokens to join self-service projects
  • self_service_signup - Boolean value, if True then self-service user creation is enabled

Example Output

{
    "SERVICES": {
        "member_role_name": "_identity_internal_role_", 
        "project_misc_fields": [
			"<first_custom_project_field>",
			"<second_custom_project_field>",
			"<third_custom_project_field>",
			"<fourth_custom_project_field>"
		], 
        "self_service_create_project": true, 
        "self_service_join_project": true, 
        "self_service_signup": true
    }
}

 

HTTP Method: POST

/MCAPI/services/project/{project_id}/join

Any user with the self-service token may join a project.

Example Body

{
    "selfServiceToken": "a3d4e5fffe"
}

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "My Cool Project",
        "description": "A description ...",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee",
        "misc_field": "value"
      },
    "role": {
        "id": "123",
        "name": "Default Role",
        "description": "Default Access"
    }
}

/MCAPI/services/project/{project_id}/init

Cloud admins may initialize self-service for any project not already initialized as self-service.

The Post should have an empty body.

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "My Cool Project",
        "description": "A description ...",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee",
        "misc_field": "value"
      }
}

/MCAPI/services/project/create

Any user may create a new project with self-service.

Example Body

{
    "project": {
        "name": "New Project Name",
        "description": "A description ..."
}

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "New Project Name",
        "description": "A description ...",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee"
      }
}

/MCAPI/services/signup

Anyone may signup a new user via self-service.

Depending on the specific backend used, the required fields will be different. In all cases, name and password are a requirement. "ad_domain" is used for Active Directory authentication in some schemes (and is optional when not in use).

Example Body

{
    "name": "jqsmith",
    "password": "SuperSecurePassword",
    "email": "john.q.smith@example.com",
    "ad_domain": "EXAMPLEDOMAIN"
}

Example Output

Status: 200 OK

{
  "user": {
    "id": "u1000",
    "username": "jqsmith",
    "email": "john.q.smith@example.com",
    "enabled": true
    "self_service_domain": "EXAMPLEDOMAIN"
  }
}

/MCAPI/services/project/{project_id}/manager

Any self-service manager of a given project may make a current project user into a self-service manager of that project.

Example Body

{
    "user_id": "asdf1234ccdee",
}

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "My Cool Project",
        "description": "A description ...",
        "enabled": true
        "self_service_managers": ["ccdfe1234", "asdf1234ccdee"],
        "self_service_token: "a3d4f589eeeeeee",
        "misc_field": "value"
      }
}

/MCAPI/services/project/reinit 

Any self-service manager for a given project may generate a new Self-Service token for that project.

The Post should have an empty body.

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "My Cool Project",
        "description": "A description ...",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee"
      }
}

/MCAPI/services/project/{project_id}

Any self-service manager of a given project may update "description", "enabled", or any of the extra fields explicitly configured for their AZ.

Example Body

{
    "description": "This is a new description",
    "enabled": True,
    "misc_field": "value",
}

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "My Cool Project",
        "description": "This is a new description",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee",
        "misc_field": "value"
      }
}

 

HTTP Method: DELETE

/MCAPI/services/project/{project_id}

Any cloud admin may disable self-service for a given project.

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "New Project Name",
        "description": "This is a new description",
        "enabled": true
        "misc_field": "value"
      }
}

/MCAPI/services/project/{project_id}/manager/{user_id}

Any self-service manager of a given project may remove a user from being a self-service manager of that project.

Example Output

Status: 200 ok

{
    "project": {
        "id": "1234",
        "name": "New Project Name",
        "description": "This is a new description",
        "enabled": true
        "self_service_managers": ["ccdfe1234"],
        "self_service_token: "a3d4f589eeeeeee",
        "misc_field": "value"
      }
}

 

Have more questions? Submit a request
Powered by Zendesk