This documentation provides docs for every authorization server endpoint. Internally by the controller and every official droplet, auth tokens are used for authentication. No GRPC request with invalid auth token is possible.
Scoping is the OAuth way to deal with permissions. Scopes are represented in a string, seperated by a whitespace.
In our case, they can also be wildcarded (*).
These scopes:
test.*other.test
will be passed as: test.* other.test on auth server rest endpoints.
The scope * will grant every permission.
You can get the scopes that are provided to the current context (but ony if this context uses the v3 controllers AuthSecretInterceptor) like this:
val scopes = MetadataKeys.SCOPES.get() // List<String>For some endpoints, there are listed authorization scope requirements. To access these endpoints, you must pass a token in the Authorization header that meets these requirements.
{
"Authorization": "Bearer <token>"
}You can gain access to an auth token by using the master token, retrieving a token through user login (/login)
and by creating a custom client with the client_credentials method and calling the (/token) endpoint to log in with this client.
The AuthorizationHandler provides various endpoints for client registration, authorization, token requests, revocation, and introspection. Below is a detailed description of each endpoint.
POST /oauth/register_client
Registers a new OAuth client, associating it with a unique client secret, grant types, and scope.
master_token(String, required): The master token for authentication (in the.secrets/auth.secretfile).client_id(String, required): The unique identifier for the client.redirect_uri(String, required): The URI to redirect to after authorization.grant_types(String, required): The grant types supported by the client.scope(String, optional): The scopes the client has access to.client_secret(String, optional): The client secret. If not provided, a random one will be generated.
- None
- 200 OK: The client was successfully registered.
{ "client_id": "client_id", "client_secret": "client_secret" } - 400 Bad Request: Missing required parameters such as
client_idorgrant_types. - 403 Forbidden: Invalid master token.
POST /oauth/authorize
Handles the authorization request for an OAuth client with PKCE (Proof Key for Code Exchange) support.
client_id(String, required): The unique identifier for the client.redirect_uri(String, required): The URI to redirect to after authorization.code_challenge_method(String, required): The challenge method. Must beS256.code_challenge(String, required): The PKCE code challenge.scope(String, required): The requested scope.
- None
- 200 OK: Authorization successful.
{ "redirectUri": "<redirect_uri>?code=<authorization_code>" } - 400 Bad Request: Missing required parameters such as
client_id,redirect_uri,scope, orcode_challenge. - 404 Not Found: Client not found.
- 400 Bad Request: Invalid challenge or unsupported grant types.
POST /oauth/token
Handles the token request to exchange the authorization code for an access token or to generate a client credentials token.
client_id(String, required): The unique identifier for the client.client_secret(String, required): The client secret.code(String, required if using authorization code flow): The authorization code.code_verifier(String, required if using PKCE): The PKCE code verifier.
- None
- 200 OK: Token successfully issued.
{ "access_token": "access_token", "scope": "scope", "exp": "expiration_time", "user_id": "user_id", "client_id": "client_id" } - 400 Bad Request: Missing required parameters such as
client_idorclient_secret. - 404 Not Found: Client not found.
- 400 Bad Request: Invalid client secret or unsupported grant type.
POST /oauth/revoke
Revokes an OAuth token, rendering it inactive.
access_token(String, required): The access token to revoke.
- None
- 200 OK: The token was successfully revoked.
- 400 Bad Request: Invalid access token.
- 500 Internal Server Error: Could not delete token.
POST /oauth/introspect
Introspects a token to verify its validity and return token details.
token(String, required): The token to introspect.
- None
- 200 OK: Token is valid and active.
{ "active": true, "token_id": "token_id", "client_id": "client_id", "scope": "scope", "exp": "expiration_time" } - 200 OK: Token is invalid or expired.
{ "active": false } - 400 Bad Request: Token is missing.
The AuthenticationHandler provides various endpoints to manage OAuth groups, users, and tokens. Below is a detailed
description of each endpoint.
PUT /group
Creates or updates an OAuth group with the specified scopes.
group_name(String, required): Name of the group.scopes(String, optional): Space-separated list of scopes for the group.
simplecloud.auth.group.save.<group_name>
- 200 OK: Success message.
- 400 Bad Request: You must specify a group name.
- 401 Unauthorized: Unauthorized.
GET /group
Retrieves details of a specific OAuth group.
group_name(String, required): Name of the group to retrieve.
simplecloud.auth.group.get.<group_name>
- 200 OK: Group details.
{ "group_name": "example_group", "scope": "read write" } - 400 Bad Request: You must specify a group name.
- 404 Not Found: Group not found.
- 401 Unauthorized: Unauthorized.
GET /groups
Fetches a list of all OAuth groups.
simplecloud.auth.group.get.*
- 200 OK: List of all groups.
[ { "group_name": "group1", "scope": "read write" }, { "group_name": "group2", "scope": "read" } ] - 401 Unauthorized: Unauthorized.
DELETE /group
Deletes a specific OAuth group.
group_name(String, required): Name of the group to delete.
simplecloud.auth.group.delete.<group_name>
- 200 OK: Success message.
- 400 Bad Request: You must specify a group name.
- 404 Not Found: Group not found.
- 401 Unauthorized: Unauthorized.
PUT /user
Creates or updates a user with the specified groups and scopes.
username(String, required): The username.password(String, required): The password.groups(String, optional): Space-separated list of groups the user belongs to.scope(String, optional): Space-separated list of scopes for the user.
simplecloud.auth.user.save
- 200 OK: Success message.
- 400 Bad Request: You must specify a username or password.
- 401 Unauthorized: Unauthorized.
GET /user
Fetches details of a specific user.
username(String, required): Name of the user to retrieve.
simplecloud.auth.user.get.<username>
- 200 OK: User details.
{ "user_id": "1234", "username": "example_user", "scope": "read write", "groups": "group1 group2" } - 400 Bad Request: You must specify a username.
- 404 Not Found: User not found.
- 401 Unauthorized: Unauthorized.
GET /users
Fetches a list of all users.
simplecloud.auth.user.get.*
- 200 OK: List of all users.
[ { "user_id": "1234", "username": "user1", "scope": "read write", "groups": "group1 group2" }, { "user_id": "5678", "username": "user2", "scope": "read", "groups": "group3" } ] - 401 Unauthorized: Unauthorized.
DELETE /user
Deletes a specific user.
user_id(String, required): The user ID to delete.
simplecloud.auth.user.delete
- 200 OK: Success message.
- 400 Bad Request: You must specify a user ID.
- 404 Not Found: User not found.
- 401 Unauthorized: Unauthorized.
POST /login
Authenticates a user and returns an access token if the username and password are valid.
username(String, required): The username.password(String, required): The password.
- 200 OK: Access token and user details.
{ "access_token": "jwt_token", "scope": "read write", "exp": 3600, "user_id": "1234", "client_id": "abcd" } - 400 Bad Request: You must specify a username and password.
- 401 Unauthorized: Invalid username or password.