Skip to content
GitLab
Menu
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
ai3
accountserver
Commits
9057794c
Commit
9057794c
authored
Jun 26, 2018
by
ale
Browse files
Start adding API reference documentation
parent
f7837166
Changes
3
Hide whitespace changes
Inline
Side-by-side
API.md
View file @
9057794c
...
...
@@ -130,3 +130,157 @@ Actions:
### web hosting (website / db / FTP account or equivalent)
...
# API Reference
## User endpoints
The following API endpoints invoke operations on an individual
user. Access is allowed for admins, and for the user itself.
Most requests dealing with encryption keys are so-called
*privileged*
requests, and will require the user's password in the
*cur_password*
parameter in order to decrypt the existing encryption keys.
### `/api/user/get`
Retrieve information about a user and all its associated resources.
Request parameters:
*
`username`
- user to fetch
*
`sso`
- SSO ticket
### `/api/user/change_password`
Change the primary authentication password for a user. This operation
will update the user's storage encryption keys, or initialize them if
they do not exist.
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
*
`cur_password`
- current valid password for the user
*
`password`
- new password (unencrypted)
### `/api/user/set_password_recovery_hint`
Sets the secondary authentication password (a hint / response pair,
used to recover the primary credentials) for a user. This operation
will update the user's storage encryption keys, or initialize them if
they do not exist yet.
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
*
`cur_password`
- current valid password for the user
*
`hint`
- the secondary authentication hint
*
`response`
- the secondary authentication response (effectively a
password, unencrypted)
### `/api/user/enable_otp`
Enable TOTP for a user. The server can generate a new TOTP secret if
necessary, or it can be generated by the caller (usually better as it
allows for a better validation UX).
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
*
`totp_secret`
- new TOTP secret (optional)
### `/api/user/disable_otp`
Disable TOTP for a user. Existing 2FA credentials will be wiped as
well.
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
### `/api/user/create_app_specific_password`
Create a new application-specific password. 2FA must already be
enabled for the user. A new random password will be generated by the
server and returned in the response. A new copy of the encryption key
will be encrypted with the new application-specific password.
ASPs are identified by a unique random ID that is also automatically
generated by the server.
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
*
`cur_password`
- current valid password for the user
*
`service`
- service that the password should be valid for
*
`notes`
- a user-controlled comment about the client
### `/api/user/delete_app_specific_password`
Delete an application-specific password (and the associated encryption
key).
Request parameters:
*
`username`
- name of the user
*
`sso`
- SSO ticket
*
`asp_id`
- ID of the app-specific password
## Resource endpoints
These API endpoints manipulate individual resources regardless of
which user they belong to. Access is normally granted to admins and to
the user that owns a resource, but some operations are restricted to
admins only.
### `/api/resource/enable`
Enable a resource (admin-only).
Request parameters:
*
`resource_id`
- resource ID
*
`sso`
- SSO ticket
*
`comment`
- notes on the operation
### `/api/resource/disable`
Disable a resource (admin-only).
Request parameters:
*
`resource_id`
- resource ID
*
`sso`
- SSO ticket
*
`comment`
- notes on the operation
### `/api/resource/move`
Move a resource between shards (admin-only).
Resources that are part of a group (for instance websites and DAV
accounts) are moved together, so this request might end up moving more
than one resource.
Request parameters:
*
`resource_id`
- resource ID
*
`sso`
- SSO ticket
*
`shard`
- new shard
### `/api/resource/create`
Create one or more resources associated with a user. Note that if
creating multiple resources, they must all belong to the same user.
Request parameters:
*
`sso`
- SSO ticket
*
`resources`
- list of resource objects to create
actions.go
View file @
9057794c
...
...
@@ -321,7 +321,7 @@ func (s *AccountService) disable2FA(ctx context.Context, tx TX, user *User) erro
type
CreateApplicationSpecificPasswordRequest
struct
{
PrivilegedRequestBase
Service
string
`json:"service"`
Comment
string
`json:"
comment
"`
Notes
string
`json:"
notes
"`
}
// Validate the request.
...
...
@@ -354,7 +354,7 @@ func (s *AccountService) CreateApplicationSpecificPassword(ctx context.Context,
asp
:=
&
AppSpecificPasswordInfo
{
ID
:
randomAppSpecificPasswordID
(),
Service
:
req
.
Service
,
Comment
:
req
.
Comment
,
Comment
:
req
.
Notes
,
}
password
:=
randomAppSpecificPassword
()
encPass
:=
pwhash
.
Encrypt
(
password
)
...
...
server/server.go
View file @
9057794c
...
...
@@ -146,8 +146,8 @@ func (s *AccountServer) Handler() http.Handler {
h
.
HandleFunc
(
"/api/user/set_password_recovery_hint"
,
s
.
withTx
(
s
.
handleSetPasswordRecoveryHint
))
h
.
HandleFunc
(
"/api/user/enable_otp"
,
s
.
withTx
(
s
.
handleEnableOTP
))
h
.
HandleFunc
(
"/api/user/disable_otp"
,
s
.
withTx
(
s
.
handleDisableOTP
))
h
.
HandleFunc
(
"/api/app_specific_password
/create
"
,
s
.
withTx
(
s
.
handleCreateApplicationSpecificPassword
))
h
.
HandleFunc
(
"/api/app_specific_password
/delete
"
,
s
.
withTx
(
s
.
handleDeleteApplicationSpecificPassword
))
h
.
HandleFunc
(
"/api/
user/create_
app_specific_password"
,
s
.
withTx
(
s
.
handleCreateApplicationSpecificPassword
))
h
.
HandleFunc
(
"/api/
user/delete_
app_specific_password"
,
s
.
withTx
(
s
.
handleDeleteApplicationSpecificPassword
))
h
.
HandleFunc
(
"/api/resource/enable"
,
s
.
withTx
(
s
.
handleEnableResource
))
h
.
HandleFunc
(
"/api/resource/disable"
,
s
.
withTx
(
s
.
handleDisableResource
))
h
.
HandleFunc
(
"/api/resource/create"
,
s
.
withTx
(
s
.
handleCreateResources
))
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment