docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DTR API docs 1.4.0 in the docs chrome + menu

This commit is contained in:
Viktor Stanchev 2015-11-12 09:59:51 -08:00
parent 00d6f01906
commit ac53cc42c4
9 changed files with 0 additions and 1812 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

416
api/dtr_1_3_accounts.md
View File

@ -1,416 +0,0 @@
+++
title = "Docker Trusted Registry Accounts API"
description = "Docker Trusted Registry 1.3 User and Organization Accounts"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 61
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 User and Organization Accounts
## List Accounts
`GET /api/v0/accounts`
```bash
$ curl --user alice:password https://dtr.domain.com/api/v0/accounts
```
Example Response:
```json
{
"accounts": [
{
"id": 1,
"type": "user",
"name": "admin",
"isActive": true
},
{
"id": 2,
"type": "user",
"name": "jlhawn",
"isActive": true
},
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": true
},
{
"id": 4,
"type": "organization",
"name": "engineering",
}
]
}
```
**Authorization**
Client must be authenticated as any user in the system.
**Status Codes**
- *401* the client is not authenticated.
- *200* success.
## Account Details
`GET /api/v0/accounts/{name}`
```bash
$ curl --user alice:password https://dtr.domain.com/api/v0/accounts/alice
```
Example Request:
```http
GET /api/v0/accounts/alice HTTP/1.1
```
Response:
```json
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as any user in the system.
**Status Codes**
- *404* no such account exists.
- *401* the client is not authenticated.
- *200* success.
## List Organizations for a User
`GET /api/v0/accounts/{name}/organizations`
```bash
$ curl --user alice:password https://dtr.domain.com/api/v0/accounts/alice/organizations
```
Example Request:
```http
GET /api/v0/accounts/alice/organizations HTTP/1.1
```
Example Response:
```json
{
"organizations": [
{
"id": 4,
"type": "organization",
"name": "engineering",
}
]
}
```
**Authorization**
Client must be authenticated as a system 'admin' user or as the user in question.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin or target user.
- *200* success.
## Create an Account
`POST /api/v0/accounts`
```bash
$ curl --user alice:password -X POST --data '{"type": "user","name": "alice","password": "watchThinkFruitNeighbor"}' --header "Content-Type: application/json" https://dtr.domain.com/api/v0/accounts
```
User and Organization names must conform to the namespace rules - lowercase
letters, numbers, or after the first character, `-` and `_`.
### Create a Managed User Account
There is no user restriction on creating a managed user account, however managed
user accounts start out inactive and the user cannot authenticate until an admin
explicitly activates the account using the activate user API endpoint.
This allows the creation of Docker Trusted Registry managed namespace reservations by an external
service, which can then activate the account when it's been verified by the external service.
Docker Trusted Registry auth settings must be in "Managed" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "user",
"name": "alice",
"password": "watchThinkFruitNeighbor"
}
```
Response:
```json
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": false
}
```
**Authorization**
Anyone - no authorization required.
**Status Codes**
- *400* invalid input, or `account already exists`
- *200* success.
### Create a User Account from LDAP
Docker Trusted Registry auth settings must be in "ldap" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "user",
"name": "robert.smith",
"ldapLogin": "robert.smith",
"password": "shakeMeanPlainBaseball"
}
```
The `name` field is the requested username to use in Docker Trusted Registry, while `ldapLogin`
should be the user's LDAP user login attribute. These need only differ if the
user prefers or if the user's LDAP login name is not compatible with valid Docker Trusted Registry
usernames.
Response:
```json
{
"id": 4,
"type": "user",
"name": "robert.smith",
"ldapLogin": "robert.smith"
}
```
**Authorization**
Anyone may create an LDAP user account, however, the account is only created if
the client provides a valid LDAP login and password.
**Status Codes**
- *400* invalid input.
- *200* success.
### Create an Organization Account
Docker Trusted Registry auth settings must be in "Managed" or "ldap" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "organization",
"name": "engineering"
}
```
Response:
```json
{
"id": 5,
"type": "organization",
"name": "engineering",
"ldapLogin": "engineering"
}
```
**Authorization**
Client must be authenticated as a global 'admin' user.
**Status Codes**
- *400* invalid input.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
## Remove an User or Organization Account
`DELETE /api/v0/accounts/{name}`
```bash
curl -v --user admin:password -X DELETE https://dtr.domain.com/api/v0/accounts/engineering
```
Example Request:
```http
DELETE /api/v0/accounts/alice HTTP/1.1
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *401* client must be authenticated.
- *403* client must be an admin.
- *204* (`No Content`) success - or account does not exist.
## Change a Managed User's Password
`POST /api/v0/accounts/{name}/changePassword`
```bash
curl -v --user admin:password -X POST --data '{"newPassword":"qwerty!@"}' --insecure --header "Content-type: application/json" https://dtr.domain.com/api/v0/accounts/alice/changePassword
```
Passwords set using this API need to be eight characters or longer.
Example Request:
```http
POST /api/v0/accounts/alice/changePassword HTTP/1.1
Content-Type: application/json
{
"oldPassword": "watchThinkFruitNeighbor",
"newPassword": "pinkCloudBehaviorDozen"
}
```
Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as the user in question or as an admin user (in
which case the `oldPassword` field may be omitted from the request body).
**Status Codes**
- *400* invalid input. (can be `password too short`)
- *401* client must be authenticated.
- *404* no such account.
- *200* success.
## Activate a Managed User
`PUT /api/v0/accounts/{name}/activate`
```bash
curl -v --user admin:password -X PUT --insecure https://dtr.domain.com/api/v0/accounts/alice/activate
```
Example Request:
```http
PUT /api/v0/accounts/alice/activate HTTP/1.1
```
Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
## Deactivate a Managed User
`PUT /api/v0/accounts/{name}/deactivate`
```bash
curl -v --user admin:password -X PUT --insecure https://dtr.domain.com/api/v0/accounts/alice/deactivate
```
Example Request:
```http
PUT /api/v0/accounts/alice/deactivate HTTP/1.1
```
Examlpe Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": false
}
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
<!--- TODO - how do I list / change the global roles assignments? --->

140
api/dtr_1_3_design_doc.md
View File

@ -1,140 +0,0 @@
+++
title = "Docker Trusted Registry API Design document"
description = "Docker Trusted Registry 1.3 API Design document"
draft = true
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3
## Organization Accounts and Repository Access Control
We need an API for fine-grained role based access control in Docker Trusted
Registry.
### Goals
1. An API for managing accounts
This includes creating an account, listing existing accounts, creating a
team within an organization, listing teamns in an organization, getting a
specific team, listing members of a team, adding and removing members
from a team (if managed whitelist) or editing ldap sync config.
2. LDAP Syncing
We need to be able to automatically sync members of a team according to
some LDAP group filter configured by an org admin.
3. An API for repositories and access control.
This includes creating a repository, listing repositories for an account,
adding collaborators to a repository, setting namespace-level access for
teams, etc.
4. Minimal or No Data Migration.
If we can help it, we’d like to not require any data migration in this
release, only schema migration.
### Non-Goals
No UI. This release will be API only.
### Design
There are two types of accounts: Users and Organizations. We will be creating a
sense of account-owned namespaces in Docker Trusted Registry much like in Docker Hub Registry.
Account-owned (non-global) repositories will have two-component names of the
form `namespace/reponame`.
Users will be able to create a repository under their own namespace and be able
to control what other users have read-only, read-write, or admin access to any
of their repositories.
System administrators can also create an Organization account, with it’s own
namespace of repositories. Organization accounts will have one or more teams
which can be managed by anyone in the initial ‘owners’ team. Teams can either
be created with a managed whitelist of users known to the system or with an
LDAP group search filter which will be periodically synced.
Any member of an organization’s owners team can create new repositories under
the organization’s namespace and even create and edit other teams. Each team
can be given read-only or read-write access to all repositories in the
organization’s namespace and/or be granted separate levels of access on a
per-repository basis. Permissions are additive, so there is no way to override
a team level permission to prevent access to a specific repository.
Teams within an organization can also be granted read-only, read-write, or
admin level access to all repositories in the organizations namespace. This
allows a team to pull, push, and/or manage repositories for an organization
but *not* manage the teams themselves.
Repositories can be set as either public or private. Public repositories can be
read by any account in the system and only written to by accounts with explicit
write access granted to them. Private repositories will not be discoverable by
any account that does not have at least explicit read access to that
repository.
User owned repositories can only be given access to the owner and other
individual user accounts, i.e., you cannot grant access to a user-owned
repository to a team of users in an organization. If this level of control is
needed on a repository then consider moving that repository within an
organization namespace.
Organization owned repositories can only be given access to the teams within
that organization, i.e., you cannot grant access to an organization-owned
repository to an individual user account or to a team in another organization.
If this level of control is needed on a repository then consider adding those
individual users to a team within the owning organization or add users in the
other organization’s team to a team within the owning organization.
### Notable Differences from Docker Hub Registry
- Repositories must be explicitly created using the API. A `docker push` will
not create a repository if it does not exist. This prevents a typo from
creating an unwanted repository in Docker Trusted Registry. This policy
will be globally enforced in Docker Trusted Registry 1.3.
- Organizations can only be created by system admins. This should prevent the
proliferation of unwanted organization accounts.
- Collaborators on user-owned repositories can be given more granularity of
access. Docker Hub Registry offers only read-write access. Docker Trusted
Registry plans to offer read-only, read-write, and admin access per
user-owned repository.
- Teams can be granted access to all repositories in an organization's
namespace. Docker Hub Registry offers team access control on a
per-repository level only, and only an organization's 'owners' team can
manage access and create new repositories. Docker Trusted Registry plans to
also offer the ability to grant a team access to (and/or the ability to
manage) all repositories under a namespace.
- Teams within an organization will be visible to all members of the
organization. In Docker Hub Registry, users are 'blind' to teams that they
themselves are not a member of. In Docker Trusted Registry, teams will be
visible to the members of the organization, but will not be able to see a
teams's members unless they are also a member of that team.
### API
#### Authentication
Clients may authenticate API requests by providing either Basic Auth
credentials (i.e., username and password) in an "Authorization" header for each
request.
**Accounts**
- [Accounts API Doc](https://gist.github.com/jlhawn/1e7e35c7eed536f4bdf2)
- [Teams API Doc](https://gist.github.com/jlhawn/9a1f24d44e9fce541cfb)
**Repositories**
- [Repositories API Doc](https://gist.github.com/jlhawn/dbdeb81a2724e913f036)
- [User-Owned Repository Access API Doc](https://gist.github.com/jlhawn/90e5442e1b1503b1f970)
- [Organization-Owned Repository Access API Doc](https://gist.github.com/jlhawn/45c8d6587f632975a345)
- [Organization-Owned Repository Namespace Access API Doc](https://gist.github.com/jlhawn/68f78af0e6b0325facd3)

203
api/dtr_1_3_repositories.md
View File

@ -1,203 +0,0 @@
+++
title = "Docker Trusted Registry Repository API"
description = "Docker Trusted Registry 1.3 Repository API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 65
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 Repositories
## List Repositories in a Namespace
`GET /api/v0/repositories/{namespace}`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/repositories/engineering
```
Example Response:
```json
{
"repositories": [
{
"id": 17,
"namespace": "don",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
},
{
"id": 32,
"namespace": "don",
"name": "private-app",
"shortDescription": "A Closed-Source Retro Turboencabulator",
"longDescription": "The original machine had a base plate of pre-famulated amulite surmounted by a malleable logarithmic casing in such a way that the two spurving bearings were in a direct line with the panametric fam. The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented.\nThe main winding was of the normal lotus-o-delta type placed in panendermic semi-boloid slots of the stator, every seventh conductor being connected by a non-reversible termie pipe to the differential girdle spring on the \"up\" end of the grammies.\nThe turbo-encabulator has now reached a high level of development, and it’s being successfully used in the operation of novertrunnions.",
"visibility": "private",
"status": "ok"
}
]
}
```
**Authorization**
Client must be authenticated as any active user in the system. Results will be
filtered to only those repositories visible to the client.
**Status Codes**
- *404* no such namespace.
- *200* success.
## View Details of a Repository
`GET /api/v0/repositories/{namespace}/{reponame}`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/repositories/engineering/public-app
```
Example Response:
```json
{
"id": 17,
"namespace": "don",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user who has visibility to the repository.
**Status Codes**
- *404* no such repository namespace exists or client not authorized.
- *200* success.
## Create a Repository
`POST /api/v0/repositories/{namespace}`
```bash
$ curl -v --user admin:password --insecure -X POST --data '{"name":"my-app"}' --header "Content-type: application/json" https://dtr.domain.com/api/v0/repositories/engineering
```
If you don't specify the `visibility`, option, it will default to `private`.
Example Request:
```http
POST /api/v0/repositories/alice HTTP/1.1
Content-Type: application/json
{
"name": "my-app",
"shortDescription": "My cool Docker application",
"longDescription": "This application does a bunch of cool stuff",
"visibility": "private"
}
```
Example Response:
```json
{
"id": 17,
"namespace": "alice",
"name": "my-app",
"shortDescription": "My cool Docker application",
"longDescription": "This application does a bunch of cool stuff",
"visibility": "private",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user who has `admin` access to the
repository namespace (i.e., user owns the repo or is a member of a team with 'admin' level access to the organization's namespace of repositories).
**Status Codes**
- *403* the client is not authorized.
- *400* invalid repository details.
- *201* success.
## Update Details of a Repository
`PATCH /api/v0/repositories/{namespace}/{reponame}`
```bash
$ curl -v --user admin:password --insecure -X PATCH --data '{"shortDescription":"slightly out of date"}' --header "Content-type: application
/json" https://192.168.18.129/api/v0/repositories/engineering/public-app
```
Any fields not preset in the body of this request will retain their existing value.
You cannot rename a repository using this API - the "name" field is ignored.
Example Request:
```
PATCH /api/v0/repositories/alice/my-app HTTP/1.1
Content-Type: application/json
{
"shortDescription": "My Cool Docker Retro Turboencablutator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a server application that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an application is this turbo-encabulator.",
"visibility": "public"
}
```
Example Response:
```json
{
"id": 17,
"namespace": "alice",
"name": "my-app",
"shortDescription": "My Cool Docker Retro Turboencablutator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a server application that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an application is this turbo-encabulator.",
"visibility": "public",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user who has `admin` access to the
repository (i.e., user owns the repo or is a member of a team with 'admin' level access to the organization's repository).
**Status Codes**
- *403* the client is not authorized.
- *400* invalid repository details.
- *200* success.
## Remove a Repository (removes db record only)
`DELETE /api/v0/repositories/{namespace}/{reponame}`
```bash
curl -v --user admin:password -X DELETE https://dtr.domain.com/api/v0/repositories/engineering/public-app
```
**Authorization**
Client must be authenticated as a user who has `admin` access to the
repository (i.e., user owns the repo or is a member of a team with 'admin' level access to the organization's repository).
**Status Codes**
- *403* the client is not authorized.
- *204* (`No Content`) success - or repository does not exist.

223
api/dtr_1_3_team_repo_access.md
View File

@ -1,223 +0,0 @@
+++
title = "Docker Trusted Registry Org Repository API"
description = "Docker Trusted Registry 1.3 Organization owned Repository API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 68
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 Organization-Owned Repository Access
Teams within an organization account can be granted `read-only`, `read-write`,
or `admin` level access to any repository owned by that organization.
**`read-only`**
- members of the team can pull from the repository
**`read-write`**
- members of the team can pull from the repository
- members of the team can push to the repository
**`admin`**
- members of the team can pull from the repository
- members of the team can push to the repository
- members of the team can manage other team's access to the repository
## List Teams Granted Access to an Organization-Owned Repository
`GET /api/v0/repositories/{namespace}/{reponame}/teamAccess`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/repositories/engineering/public-app/teamAccess
```
Example Response:
```json
{
"teamAccessList": [
{
"accessLevel": "read-write",
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
}
},
{
"accessLevel": "read-only",
"team": {
"id": 10,
"orgID": 22,
"type": "managed",
"name": "product",
"description": "Product Managers"
}
}
],
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organization.
- *403* the client is not authorized.
- *200* success.
## List Repository Access Grants for a Team
`GET /api/v0/accounts/{name}/teams/{teamname}/repositoryAccess`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/accounts/engineering/teams/dev/repositoryAccess
```
Example Response:
```json
{
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
},
"repositoryAccessList": [
{
"accessLevel": "read-write",
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
},
{
"accessLevel": "read-only",
"repository": {
"id": 52,
"namespace": "dtr",
"name": "private-app-2",
"shortDescription": "Another Private App for Docker Trusted Registry",
"longDescription": "We're still building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
]
}
```
**Authorization**
Client must be authenticated as a user who owns the organization the team is
in or be a member of that team.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organization.
- *400* the team does not belong to the organization.
- *403* the client is not authorized.
- *200* success.
## Set a Team's Access to an Organization-Owned Repository
`PUT /api/v0/repositories/{namespace}/{reponame}/teamAccess/{teamname}`
```bash
$ curl -v --user admin:password --insecure -X PUT --header "Content-type: application/json" --data '{"accessLevel":"read-write"}' https://dtr.domain.com/api/v0/repositories/engineering/public-app/teamAccess/dev
```
Example Request:
```http
PUT /api/v0/repositories/dtr/private-app/teamAccess/13 HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-write",
}
```
Example Response:
```json
{
"accessLevel": "read-write",
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
},
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* repository is not owned by an organization.
- *400* the team does not belong to the owning organization.
- *403* the client is unauthorized.
- *200* success.
## Revoke a Team's Access to an Organization-Owned Repository
`DELETE /api/v0/repositories/{namespace}/{reponame}/teamAccess/{teamname}`
```bash
$ curl -v --user admin:password --insecure -X DELETE https://dtr.domain.com/api/v0/repositories/engineering/public-app/teamAccess/dev
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organiztion.
- *403* the client is not authorized.
- *204* (`No Content`) success - or team is not in the access list or there is no such team in the organization.

201
api/dtr_1_3_team_repo_namespace_access.md
View File

@ -1,201 +0,0 @@
+++
title = "Docker Trusted Registry Org Namespace API"
description = "Docker Trusted Registry 1.3 Organization owned Namespace API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 69
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 Organization-Owned Repository Namespace Access
Teams within an organization account can be granted `read-only`, `read-write`,
or `admin` level access to the entire namespace of repositories owned
by that organization.
**`read-only`**
- members of the team can pull from any repository under the organization's
namespace
**`read-write`**
- members of the team can pull from any repository under the organization's
namespace
- members of the team can push to any repository under the organization's
namespace
**`admin`**
- members of the team can pull from any repository under the organization's
namespace
- members of the team can push to any repository under the organization's
namespace
- members of the team can manage other team's access to any repository under
the organization's namespace
- members of the team can create new repositories under the organization's
namespace
## List Teams Granted Access to an Organization-Owned Namespace of Repositories
`GET /api/v0/repositoryNamespaces/{namespace}/teamAccess`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/repositoriesNamespaces/engineering/teamAccess
```
Example Response:
```json
{
"teamAccessList": [
{
"accessLevel": "read-write",
"team": {
"id": 7,
"orgID": 22,
"type": "managed",
"name": "dev",
"description": "Developers"
}
},
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
}
}
],
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
namespace.
**Status Codes**
- *400* the namespace is not owned by an organization.
- *403* the client is not authorized.
- *404*
- *200* success.
## Get a Team's Granted Access to an Organization-Owned Namespace of Repositories
`GET /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
```bash
$ curl -v --user admin:password --insecure -X GET https://dtr.domain.com/api/v0/repositoryNamespaces/engineering/teamAccess/lead
```
Example Response:
```json
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
},
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
namespace, is a system admin, member of the organization's "owners" team, or
is a member of the team in question.
**Status Codes**
- *400* the namespace is not owned by an organization.
- *403* the client is not authorized.
- *200* success.
## Set a Team's Access to an Organization-Owned Namespace of Repositories
`PUT /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
```bash
curl -v --user admin:password --insecure -X PUT --header "Content-type: application/json" --data '{"accessLevel":"admin"}' https://dtr.domain.com/api/v0/repositoryNamespaces/engineering/teamAccess/lead
```
Example Request:
```http
PUT /api/v0/repositoryNamespaces/engineering/teamAccess/8` HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-only",
}
```
Example Response:
```json
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
},
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
namespace.
**Status Codes**
- *400* namespace is not owned by an organization.
- *400* the team does not belong to the owning organization.
- *403* the client is unauthorized.
- *200* success.
## Revoke a Team's Access to an Organization-Owned Namespace of Repositories
`DELETE /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
```bash
$ curl -v --user admin:password --insecure -X DELETE https://dtr.domain.com/api/v0/repositoryNamespaces/engineering/teamAccess/lead
```
**Authorization**
Client must be authenticated as a user who has 'admin' level access to the
namespace.
**Status Codes**
- *400* the repository is not owned by an organization.
- *403* the client is not authorized.
- *204* (`No Content`) success - or team does not exist in the access list or there is no such team in the organization.

305
api/dtr_1_3_teams.md
View File

@ -1,305 +0,0 @@
+++
title = "Docker Trusted Registry User and Org API"
description = "Docker Trusted Registry 1.3 User and Organization Accounts API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 62
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 Teams
As with Docker HUb, Docker Trusted Registry teams of users can only exist within an Organization.
## List Teams in an Organization
`GET /api/v0/accounts/{name}/teams`
```bash
$ curl --insecure -v --user admin:password https://dtr.domain.com/api/v0/accounts/engineering/teams
```
Example Response:
```json
{
"teams": [
{
"id": 4,
"orgID": 4,
"type": "managed",
"name": "owners",
"description": ""
},
{
"id": 5,
"orgID": 4,
"type": "managed",
"name": "testers",
"description": "i have altered the description, pray that i do not alter it any further"
}
]
}
```
**Authorization**
Client must be authenticated as a member of the organization containing the team(s).
**Status Codes**
- *403* the client is not authorized.
- *404* the Organization has no teams.
- *200* success.
## View Details of a Team
`GET /api/v0/accounts/{name}/teams/{teamname}`
```bash
$ curl --insecure -v --user admin:password https://dtr.domain.com/api/v0/accounts/engineering/teams/qa
```
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "managed",
"name": "testers",
"description": "I have altered the description, pray that I do not alter it any further"
}
```
**Authorization**
Client must be authenticated as a member of the organization containing the team(s).
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## List a Team's Members
`GET /api/v0/accounts/{name}/teams/{teamname}/members`
```bash
$ curl --insecure -v --user admin:password https://dtr.domain.com/api/v0/accounts/engineering/teams/qa/members
```
Example Response:
```json
{
"members": [
{
"id": 8,
"type": "user",
"name": "midei",
"isActive": true
},
{
"id": 10,
"type": "user",
"name": "rajat",
"isActive": true
},
{
"id": 12,
"type": "user",
"name": "banjot",
"isActive": true
},
{
"id": 15,
"type": "user",
"name": "jon",
"isActive": true
}
]
}
```
**Authorization**
Client must be authenticated as a system admin, a member of the "owners" team
in the organization, or a member of the team in question.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## Check if a User is a Member of a Team
`GET /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
```bash
$ curl --insecure -v --user admin:password -X GET https://dtr.domain.com/api/v0/accounts/engineering/teams/qa/members/test
```
**Authorization**
Client must be authenticated as a user who has visibility into the team
(i.e., a member of the team or an owner of the organization).
**Status Codes**
- *403* the client is not authorized.
- *404* no such teams exists or user is not a member.
- *204* success (user is a member).
## Create a Team in an Organization
`POST /api/v0/accounts/{name}/teams`
```bash
$ curl --insecure -v --user admin:password -X POST --data '{"name": "qa", "type": "managed"}' --header "Content-type: application/json" https://dtr.domain.com/api/v0/accounts/engineering/teams
```
Example Request:
```http
POST /api/v0/accounts/engineering/teams HTTP/1.1
Content-Type: application/json
{
"name": "qa",
"description": "QA Engineering Team",
"type": "ldap",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "ldap",
"name": "qa",
"description": "QA Engineering Team",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *400* invalid team name or LDAP filter.
- *201* success.
## Update a Teams's Details
`PATCH /api/v0/accounts/{name}/teams/{teamname}`
```bash
$ curl --insecure -v --user admin:password -X PATCH --data '{"description":"add one"}' --header "Content-type: application/json" https://dtr.domain.com/api/v0/accounts/engineering/teams/qa
```
Example Request:
```http
POST /api/v0/accounts/engineering/teams/5 HTTP/1.1
Content-Type: application/json
{
"name": "qualityassurance",
"description": "Quality Assurance Engineers"
}
```
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "ldap",
"name": "qualityassurance",
"description": "Quality Assurance Engineers",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *404* no such team exists.
- *403* the client is not authorized.
- *400* invalid updated detail values.
- *200* success.
## Add a User to a Team (if not LDAP synced).
`PUT /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
```bash
$ curl --insecure -v --user admin:password -X PUT https://dtr.domain.com/api/v0/accounts/engineering/teams/qa/members/alice
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team or user.
- *200* success.
## Remove a User from a Team (if not LDAP synced).
`DELETE /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
```bash
$ curl --insecure -v --user admin:password -X DELETE https://dtr.domain.com/api/v0/accounts/engineering/teams/qa/members/alice
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *204* (`No Content`) success - or user is not in the team.
## Remove a Team.
`DELETE /api/v0/accounts/{name}/teams/{teamname}`
```bash
$ curl --insecure -v --user admin:password -X DELETE https://dtr.domain.com/api/v0/accounts/engineering/teams/qa
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *204* (`No Content`) success - or team does not exist.

158
api/dtr_1_3_user_repo_access.md
View File

@ -1,158 +0,0 @@
+++
title = "Docker Trusted Registry User Repository API"
description = "Docker Trusted Registry 1.3 User-Owned Repository Acces"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 66
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3 User-Owned Repository Access
User accounts can be granted `read-only`, `read-write`, or `admin` level access
to any repository owned by another user account.
**`read-only`**
- user can pull from the repository
**`read-write`**
- user can pull from the repository
- user can push to the repository
**`admin`**
- user can pull from the repository
- user can push to the repository
- user can manage other users' access to the repository
## List Users Granted Access to a User-Owned Repository
`GET /api/v0/repositories/{namespace}/{reponame}/userAccess`
```bash
curl -v --user josh:password --insecure https://dtr.domain.com/api/v0/repositories/josh/public-app/userAccess
```
Example Response:
```json
{
"repository": {
"id": 28,
"namespace": "josh",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
},
"userAccessList": [
{
"accessLevel": "read-write",
"user": {
"id": 14,
"type": "user",
"name": "brian",
"isActive": true
}
},
{
"accessLevel": "read-write",
"user": {
"id": 6,
"type": "user",
"name": "don",
"isActive": true
}
}
]
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by a user.
- *403* the client is not authorized.
- *200* success.
## Set a User's Access to a User-Owned Repository
`PUT /api/v0/repositories/{namespace}/{reponame}/userAccess/{grantee}`
```bash
curl -v --user josh:password --insecure -X PUT --header "Content-type: application/json" --data '{"accessLevel":"read-write"}' https://dtr.domain.com/api/v0/repositories/alice/public-app/userAccess/brian
```
Example Request:
```http
PUT /api/v0/repositories/josh/public-app/userAccess/brian HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-write",
}
```
Example Response:
```json
{
"accessLevel": "read-write",
"user": {
"id": 14,
"type": "user",
"name": "brian",
"isActive": true
},
"repository": {
"id": 28,
"namespace": "josh",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* repository is not owned by a user.
- *403* the client is unauthorized.
- *200* success.
## Revoke a User's Access to a User-Owned Repository
`DELETE /api/v0/repositories/{namespace}/{reponame}/userAccess/{grantee}`
```bash
$ curl -v --user josh:password --insecure -X DELETE https://dtr.domain.com/api/v0/repositories/josh/public-app/userAccess/user
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by a user.
- *403* the client is not authorized.
- *204* (`No Content`) success - or user is not in the access list.

24
api/dtr_api.md
View File

@ -1,24 +0,0 @@
+++
title = "Docker Trusted Registry"
description = "Docker Trusted Registry APIs"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 2
[menu.main]
parent = "mn_reference"
+++
# Docker Trusted Registry APIs
The Docker Trusted Registry Accounts & Reps APIs allow you to integrate Docker Trusted Registry with your enterprise's
organizational structure by providing fine-grained, role-based access control for your repositories.
The following documents detail the API:
- [Docker Trusted Registry Accounts & Repos API: Intro & Overview](/docker-trusted-registry/api/)
- [Accounts API Doc](dtr_1_3_accounts.md)
- [Teams API Doc](dtr_1_3_teams.md)
- [Repositories API Doc](dtr_1_3_repositories.md)
- [User-Owned Repository Access API Doc](dtr_1_3_user_repo_access.md)
- [Organization-Owned Repository Access API Doc](dtr_1_3_team_repo_access.md)
- [Organization-Owned Repository Namespace Access API Doc](dtr_1_3_team_repo_namespace_access.md)

142
api/index.md
View File

@ -1,142 +0,0 @@
+++
title = "Docker Trusted Registry Accounts & Repos API: Intro & Overview"
description = "Overview of the structure and design of the Docker Trusted Registry Accounts & Repos API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
[menu.main]
parent = "smn_dtrapi"
+++
# Docker Trusted Registry 1.3: Accounts & Repos API
## Introduction
The Accounts & Repos API lets you integrate Docker Trusted Registry with your enterprise's organizational structure by providing fine-grained, role-based access control for your repositories. Specifically, this API provides:
* An API for account management, including creating an account, listing existing accounts, creating a team within an organization, listing teams in an organization, getting a specific team, listing members of a team, adding and removing members from a team (if using a managed whitelist), or editing LDAP syncing configuration.
* Methods for syncing members of a team in Docker Trusted Registry with an LDAP group filter configured by an admin.
* An API for repository management and access control, including creating a repository, listing repositories for an account, adding collaborators to a repository, setting namespace-level access for teams, etc.
The API is designed so that minimal data migration is required, only schema migration. There is no UI accompanying this API.
## Overview
This API defines two types of accounts that can own repositories: Users and Organizations. Account-owned (i.e., non-global) repos define a namespace similar to that of the Docker Hub, with two component names in the form `namespace/reponame`.
Repositories can be either public or private. Public repositories can be
read by any account in the system, but can only be written to by accounts granted explicit write access. Private repositories cannot be discovered by
any account that does not have at least explicit read access to that
repository.
### User accounts
Docker Trusted Registry users can create a repository under their own namespace and can control which other users have read-only, read-write, or admin access to any
of their repositories.
User owned repositories can only be accessed by the owner and other
individual user accounts, i.e., you cannot grant access to a user-owned
repository to a team of users in an organization. If a repository requires this level of control, consider moving it within an organization namespace.
When the Docker Trusted Registry web admin tool is used to assign users global "read-only",
"read-write", or managed "admin" roles, they will have that access level to all
repositories. You can access and modify these roles with the API, using the
`_global` organization. However, you must have admin access in order to view and
edit the `_global` organization.
### Organization accounts
System administrators can also create an Organization account, with its own
namespace of repositories. Organization accounts are comprised of one or more teams which can be managed by anyone in an initial ‘owners’ team which is created by default. Teams can be created with either a managed whitelist of users known to the system or with an LDAP group search filter which is periodically synced automatically.
Any member of an organization’s owners team can create new repositories under
the organization’s namespace and can also create and edit other teams. Each team
can be given read-only or read-write access to all repositories in the
organization’s namespace and/or be granted separate levels of access on a
per-repository basis. However, permissions are additive, so you cannot override
a team level permission to prevent access to a specific repository.
Teams within an organization can also be granted read-only, read-write, or
admin level access to all repositories in the organizations namespace. This
allows a team to pull, push, and manage repositories for an organization,
but *not* manage the teams themselves.
Organization-owned repositories can only be given access to the teams within
that organization, i.e., you cannot grant access to an organization-owned
repository to an individual user account or team in another organization.
If this level of control is needed on a repository, you can add those
individual users to a team within the owning organization or add users in the
other organization’s team to a team within the owning organization.
### Notable differences from Docker Hub
- Repositories must be explicitly created using the API. A `docker push` will
not create a repository if it does not exist. This prevents a typo from
creating an unwanted repository in Docker Trusted Registry. This policy will be globally enforced
in Docker Trusted Registry 1.3.
- Organizations can only be created by system admins. This should prevent the
proliferation of unwanted organization accounts.
- Collaborators on user-owned repositories can be given more granular
access than on Docker Hub. Docker Hub Registry offers only read-write access.
Docker Trusted Registry offers read-only, read-write, and admin access for
each user-owned repository.
- Teams can be granted access to all repositories in an organization's
namespace. Docker Hub Registry offers team access control on a
per-repository level only, and only an organization's 'owners team can
manage access and create new repositories. Further, in the future, Docker
Trusted Registry will offer the ability to grant a team access and/or
management privileges to all repositories under a namespace.
- Teams within an organization are visible to all members of the
organization. In Docker Hub Registry, users are 'invisible' to teams to which
they do not belong. In Docker Trusted Registry, teams will be
visible to the members of the organization, but will not be able to see a
teams's members unless they are also a member of that team.
### Authentication
Clients authenticate API requests by providing Basic Auth credentials (
username and password) via an "Authorization" header for each request.
```bash
$ curl --user readuser:password https://dtr.domain.com/api/v0/accounts
{
"accounts": [
{
"id": 1,
"type": "user",
"name": "admin",
},
{
"id": 2,
"type": "user",
"name": "readuser",
},
{
"id": 3,
"type": "user",
"name": "user",
}
]
}
```
> **Note**: If you are using Docker Trusted Registry's automatically generated, self-signed SSL
> certificate
> then you'll need to add `--insecure` to the curl examples.
### API Documentation
The following documents detail the API:
- [Accounts API Doc](dtr_1_3_accounts.md)
- [Teams API Doc](dtr_1_3_teams.md)
- [Repositories API Doc](dtr_1_3_repositories.md)
- [User-Owned Repository Access API Doc](dtr_1_3_user_repo_access.md)
- [Organization-Owned Repository Access API Doc](dtr_1_3_team_repo_access.md)
- [Organization-Owned Repository Namespace Access API Doc](dtr_1_3_team_repo_namespace_access.md)