Glewlwyd API description

Experimental Single Sign On server, OAuth2, Openid Connect, multiple factor authentication with, HOTP/TOTP, FIDO2, TLS Certificates, etc. extensible via plugins

Glewlwyd API description

This document is intended to describe Glewlwyd’s core API endpoints. Glewlwyd’s core API endpoints are used to manage core functionalities data.

Endpoints authentication
Prefix
Content-type
Error response
Configuration
- Get server configuration
Plugins and modules management
Users management
Clients management
Scopes management
API Keys management
User authentication
Grant scopes
- Get list of granted scopes for a client by the user
- Update granted scope for a client by a user
User profile
Profile delegation
Authentication Scheme APIs

Endpoints authentication

All the endpoints require proper authentication to provide their service. The authentication method used is a session cookie. For each endpoint, the scope required will be defined in the Security paragraph. The admin scope name is g_admin, the profile scope name is g_profile, but these values can be changed in the configuration file.

Prefix

All URLs are based on the prefix you will setup. In this document, all endpoints will assume they use the prefix /api.

Content-type

All request and response body use application/json content-type.

Error response

The HTTP status codes used are the following:

200 OK: no error
400 Invalid parameters: The user has sent invalid data. The details of all the errors may be present in the response body
401 Unauthorized: The user isn’t authorized
403 Forbidden: The user isn’t allowed
404 Not found: The specified resource doesn’t exist
500 Server error: An error occurred on the server

Configuration

Get server configuration

This endpoint is the only one accessible directly from the root of the server.

URL

/config

Method

GET

Success response

Code 200

Content

{
  "api_prefix": string, prefix to access the APIs
  "admin_scope": string, name of the admin scope
  "profile_scope": string, name of the profile scope
  "delete_profile": string, "yes" if the user is allowed to delete its profile, "no" otherwise
}

Example

{
  "api_prefix":"api",
  "admin_scope":"g_admin",
  "profile_scope":"g_profile",
  "delete_profile": "no"
}

Plugins and modules management

Get all modules available

Return the list of all modules available for all types of modules

URL

/api/mod/type/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

{
  user: [
    name: string,
    display_name: string
    description: string
  ],
  client: [
    name: string,
    display_name: string
    description: string
  ],
  scheme: [
    name: string,
    display_name: string
    description: string
  ],
  plugin: [
    name: string,
    display_name: string
    description: string
  ]
}

Example

{
  "user":[
    {
      "name":"http",
      "display_name":"HTTP auth backend user module",
      "description":"Module to store users in the database"
    },
    {
      "name":"mock",
      "display_name":"Mock user module",
      "description":"Mock user module for glewlwyd tests"
    }
  ],
  "client":[
    {
      "name":"mock",
      "display_name":"Mock scheme module",
      "description":"Mock scheme module for glewlwyd tests"
    },
    {
      "name":"database",
      "display_name":"Database backend client module",
      "description":"Module to store clients in the database"
    }
  ],
  "scheme":[
    {
      "name":"mock",
      "display_name":"Mock",
      "description":"Mock scheme module for glewlwyd tests"
    },
    {
      "name":"retype-password",
      "display_name":"Short session password",
      "description":"Glewlwyd authentification via user password with a short session duration"
    }
  ],
  "plugin":[
    {
      "name":"mock",
      "display_name":"Mock plugin",
      "description":"Mock plugin description"
    },
    {
      "name":"oauth2-glewlwyd",
      "display_name":"Glewlwyd OAuth2 plugin",
      "description":"Plugin for legacy Glewlwyd OAuth2 workflow"
    }
  ]
}

Reload all modules

Reload all the modules and instances, useful if you have multiple Glewlwyd instances connected to the same database

URL

/api/mod/reload/

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Get all user module instances available

Return the list of all instances available for user modules

URL

/api/mod/user/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

[{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}]

Example

[
  {
    "module":"mock",
    "name":"mock",
    "display_name":"Mock user module",
    "order_rank":0,
    "parameters":{
      "username-prefix":"",
      "password":"password"
    },
    "readonly":false,
    "enabled":true
  }
]

Get a user module instance

Return the details of a user module instance

URL

/api/mod/user/{name}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Content

{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}

Example

{
  "module":"mock",
  "name":"mock",
  "display_name":"Mock user module",
  "order_rank":0,
  "parameters":{
    "username-prefix":"",
    "password":"password"
  },
  "readonly":false,
  "enabled":true
}

Code 404

Module not found

Add a new user module instance

URL

/api/mod/user/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  module: string, name of the module, must be an existing user module available
  name: string, name of the instance, maximum 128 characters
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a user
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing user module instance

URL

/api/mod/user/{name}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Body Parameters

{
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a user
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance updated

Code 404

Instance not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing user module instance

URL

/api/mod/user/{name}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Instance removed

Code 404

Instance not found

Enable or disable an existing user module instance

URL

/api/mod/user/{name}/{action}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance action: either enable or disable or reset

Success response

Code 200

Action executed

Code 404

Instance not found

Get all user middleware module instances available

Return the list of all instances available for user middleware modules

URL

/api/mod/user_middleware/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

[{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  enabled: boolean
}]

Example

[
  {
    "module":"mock",
    "name":"mock",
    "display_name":"Mock user middleware module",
    "order_rank":0,
    "parameters":{
      "username-prefix":"",
      "password":"password"
    },
    "enabled":true
  }
]

Get a user middleware module instance

Return the details of a user middleware module instance

URL

/api/mod/user_middleware/{name}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Content

{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  enabled: boolean
}

Example

{
  "module":"mock",
  "name":"mock",
  "display_name":"Mock user module",
  "order_rank":0,
  "parameters":{
    "username-prefix":"",
    "password":"password"
  },
  "enabled":true
}

Code 404

Module not found

Add a new user middleware module instance

URL

/api/mod/user_middleware/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  module: string, name of the module, must be an existing user module available
  name: string, name of the instance, maximum 128 characters
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a user
}

Success response

Code 200

Instance added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing user middleware module instance

URL

/api/mod/user_middleware/{name}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Body Parameters

{
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a user
}

Success response

Code 200

Instance updated

Code 404

Instance not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing user middleware module instance

URL

/api/mod/user_middleware/{name}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Instance removed

Code 404

Instance not found

Enable or disable an existing user middleware module instance

URL

/api/mod/user_middleware/{name}/{action}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance action: either enable or disable or reset

Success response

Code 200

Action executed

Code 404

Instance not found

Get all client module instances available

Return the list of all instances available for client modules

URL

/api/mod/client/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

[{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}]

Example

[
  {
    "module":"mock",
    "name":"mock",
    "display_name":"Mock client module",
    "order_rank":0,
    "parameters":{
      "username-prefix":"",
      "password":"password"
    },
    "readonly":false,
    "enabled":true
  }
]

Get a client module instance

Return the details of a client module instance

URL

/api/mod/client/{name}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Content

{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}

Example

{
  "module":"mock",
  "name":"mock",
  "display_name":"Mock client module",
  "order_rank":0,
  "parameters":{
    "username-prefix":"",
    "password":"password"
  },
  "readonly":false,
  "enabled":true
}

Code 404

Module not found

Add a new client module instance

URL

/api/mod/client/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  module: string, name of the module, must be an existing client module available
  name: string, name of the instance, maximum 128 characters
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a client
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing client module instance

URL

/api/mod/client/{name}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Body Parameters

{
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a client
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance updated

Code 404

Instance not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing client module instance

URL

/api/mod/client/{name}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Instance removed

Code 404

Instance not found

Enable or disable an existing client module instance

URL

/api/mod/client/{name}/{action}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance action: either enable or disable or reset

Success response

Code 200

Action executed

Code 404

Instance not found

Get all user auth scheme module instances available

Return the list of all instances available for user auth scheme modules

URL

/api/mod/scheme/

Method

GET

Security

user with scope g_admin authorized.

URL Parameters

Success response

Code 200

Content

[{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  enabled: boolean
}]

Example

[
  {
    "module":"mock",
    "name":"mock_scheme_42",
    "display_name":"Mock 42",
    "expiration":600,
    "max_use":0,
    "parameters":{
      "mock-value":"42"
    },
    "allow_user_register":true,
    "enabled":true
  }
]

Get a user auth scheme module instance

Return the details of a user auth scheme module instance

URL

/api/mod/scheme/{name}

Method

GET

Security

user with scope g_admin authorized.

URL Parameters

name: name of the instance

Success response

Code 200

Content

{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  enabled: boolean
}

Example

{
  "module":"mock",
  "name":"mock_scheme_42",
  "display_name":"Mock 42",
  "expiration":600,
  "max_use":0,
  "parameters":{
    "mock-value":"42"
  },
  "allow_user_register":true,
  "enabled":true
}

Code 404

Module not found

Add a new user auth scheme module instance

URL

/api/mod/scheme/

Method

POST

Security

user with scope g_admin authorized.

Body Parameters

{
  module: string, name of the module, must be an existing user auth scheme module available
  name: string, name of the instance, maximum 128 characters
  display_name: string, long name of the instance, maximum 256 characters
  duration: number, duration of the scheme authentication in seconds
  max_use: number, maximum use of the scheme authentication per session
  parameters: object, parameters used for the initialization of this instance
}

Success response

Code 200

Instance added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing user auth scheme module instance

URL

/api/mod/scheme/{name}

Method

PUT

Security

user with scope g_admin authorized.

URL Parameters

name: name of the instance

Body Parameters

{
  display_name: string, long name of the instance, maximum 256 characters
  duration: number, duration of the scheme authentication in seconds
  max_use: number, maximum use of the scheme authentication per session
  parameters: object, parameters used for the initialization of this instance
}

Success response

Code 200

Instance updated

Code 404

Instance not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing user auth scheme module instance

URL

/api/mod/scheme/{name}

Method

DELETE

Security

user with scope g_admin authorized.

URL Parameters

name: name of the instance

Success response

Code 200

Instance removed

Code 404

Instance not found

Enable or disable an existing user auth scheme module instance

URL

/api/mod/scheme/{name}/{action}

Method

PUT

Security

user with scope g_admin authorized.

URL Parameters

name: name of the instance action: either enable or disable or reset

Success response

Code 200

Action executed

Code 404

Instance not found

Get all plugin module instances available

Return the list of all instances available for plugin modules

URL

/api/mod/plugin/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

[{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}]

Example

[
  {
    "module":"oauth2-glewlwyd",
    "name":"glwd",
    "display_name":"OAuth2 Glewlwyd plugin",
    "parameters":{
      "jwt-type":"sha",
      "jwt-key-size":"256",
      "key":"secret",
      "access-token-duration":3600,
      "refresh-token-duration":1209600,
      "code-duration":600,
      "refresh-token-rolling":true,
      "auth-type-code-enabled":true,
      "auth-type-implicit-enabled":true,
      "auth-type-password-enabled":true,
      "auth-type-client-enabled":true,
      "auth-type-refresh-enabled":true,
      "scope":[
        {
          "name":"g_profile",
          "refresh-token-rolling":true
        },
        {
          "name":"scope1",
          "refresh-token-rolling":true
        },
        {
          "name":"scope2",
          "refresh-token-rolling":false,
          "refresh-token-duration":7200
        }
      ]
    },
    "enabled":true
  }
]

Get a plugin module instance

Return the details of a plugin module instance

URL

/api/mod/plugin/{name}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Content

{
  module: string, name of the module
  name: string, name of the instance
  display_name: string
  parameters: object, parameters used for the initialization of this instance
  order_rank: number
  readonly: boolean
  enabled: boolean
}

Example

{
  "module":"oauth2-glewlwyd",
  "name":"glwd",
  "display_name":"OAuth2 Glewlwyd plugin",
  "parameters":{
    "jwt-type":"sha",
    "jwt-key-size":"256",
    "key":"secret",
    "access-token-duration":3600,
    "refresh-token-duration":1209600,
    "code-duration":600,
    "refresh-token-rolling":true,
    "auth-type-code-enabled":true,
    "auth-type-implicit-enabled":true,
    "auth-type-password-enabled":true,
    "auth-type-client-enabled":true,
    "auth-type-refresh-enabled":true,
    "scope":[
      {
        "name":"g_profile",
        "refresh-token-rolling":true
      },
      {
        "name":"scope1",
        "refresh-token-rolling":true
      },
      {
        "name":"scope2",
        "refresh-token-rolling":false,
        "refresh-token-duration":7200
      }
    ]
  },
  "enabled":true
}

Code 404

Module not found

Add a new plugin module instance

URL

/api/mod/plugin/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  module: string, name of the module, must be an existing plugin module available
  name: string, name of the instance, maximum 128 characters
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a plugin
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing plugin module instance

URL

/api/mod/plugin/{name}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Body Parameters

{
  display_name: string, long name of the instance, maximum 256 characters
  parameters: object, parameters used for the initialization of this instance
  order_rank: number, priority of this instance to get a plugin
  readonly: boolean, set to true if the instance is in read only mode
}

Success response

Code 200

Instance updated

Code 404

Instance not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing plugin module instance

URL

/api/mod/plugin/{name}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance

Success response

Code 200

Instance removed

Code 404

Instance not found

Enable or disable an existing plugin module instance

URL

/api/mod/plugin/{name}/{action}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the instance action: either enable or disable or reset

Success response

Code 200

Action executed

Code 404

Instance not found

Users management

Get a list of users available

Return a list of users available

URL

/api/user/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

offset: number, the offset to start the list, default 0 limit: number, the maximal number of elements in the list, default 100 source: string, the instance name to limit the result, if not set, all instances will be used pattern: string, the pattern to filter the result

Success response

Code 200

Content

[{
  username: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, mandatory
  name: string, optional
  email: string, optional
  other values: string or array of strings, optional, depends on what's returned by the module instance
}]

Example

[
  {
    username: "user1",
    scope: [
      "g_profile",
      "scope1",
      "scope2"
    ],
    enabled: true,
    name: "Dave Lopper",
    email: "user1@glewlwyd",
    alias: [
      "dev",
      "plop"
    ]
  },
  {
    username: "user2",
    scope: [
      "g_profile"
    ],
    enabled: true,
    name: "Dave Lopper 2",
    email: "user2@glewlwyd"
  }
]

Get a user

Return the details of a plugin module instance

URL

/api/user/{username}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

username: username to return, mandatory source: user module instance to look for the user, optional, if not set look on all instances

Success response

Code 200

Content

{
  username: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, mandatory
  name: string, optional
  email: string, optional
  other values: string or array of strings, optional, depends on what's returned by the module instance
}

Example

{
  username: "user1",
  scope: [
    "g_profile",
    "scope1",
    "scope2"
  ],
  enabled: true,
  name: "Dave Lopper",
  email: "user1@glewlwyd",
  alias: [
    "dev",
    "plop"
  ]
}

Code 404

User not found

Add a new user

URL

/api/user/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

source: user module instance to look for the user, optional, if not set, the first instance in write mode in order rank will host the new user

Body Parameters

{
  username: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  password: string, optional, if not set, the user won't be able to authenticate
  enabled: boolean, optional, default true
  name: string, optional
  email: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

User added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing user

URL

/api/user/{username}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

username: username of the user to update source: user module instance to look for the user, optional, if not set look on all instances

Body Parameters

{
  username: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, optional, default true
  name: string, optional
  email: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

User updated

Code 404

User not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing user

URL

/api/user/{username}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

username: username of the user to delete

Success response

Code 200

User removed

Code 404

User not found

Clients management

Get a list of clients available

Return a list of clients available

URL

/api/client/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

Success response

Code 200

Content

[{
  client_id: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, mandatory
  name: string, optional
  description: string, optional
  confidential: boolean, optional
  other values: string or array of strings, optional, depends on what's returned by the module instance
}]

Example

[
  {
    client_id: "client1",
    scope: [
      "scope1",
      "scope2"
    ],
    enabled: true,
    name: "First client",
    confidential: true,
    redirect_uri: [
      "http://example.com/"
    ]
  },
  {
    client_id: "client2",
    scope: [
      "scope1"
    ],
    enabled: true,
    name: "Second client",
    confidential: false,
    redirect_uri: [
      "http://another.example.com"
    ]
  }
]

Get a client

Return the details of a plugin module instance

URL

/api/client/{client_id}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

client_id: client_id to return, mandatory source: client module instance to look for the client, optional, if not set look on all instances

Success response

Code 200

Content

{
  client_id: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, mandatory
  name: string, optional
  description: string, optional
  confidential: boolean, optional
  other values: string or array of strings, optional, depends on what's returned by the module instance
}

Example

{
  client_id: "client1",
  scope: [
    "scope1",
    "scope2"
  ],
  enabled: true,
  name: "First client",
  confidential: true,
  redirect_uri: [
    "http://example.com/"
  ]
}

Code 404

Client not found

Add a new client

URL

/api/client/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

source: client module instance to look for the client, optional, if not set, the first instance in write mode in order rank will host the new client

Body Parameters

{
  client_id: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  password: string, optional, if not set, the client won't be able to authenticate
  enabled: boolean, optional, default true
  name: string, optional
  description: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

Client added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing client

URL

/api/client/{client_id}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

client_id: client_id of the client to update source: client module instance to look for the client, optional, if not set look on all instances

Body Parameters

{
  client_id: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  password: string, optional, if not set, the client won't be able to authenticate
  enabled: boolean, optional, default true
  name: string, optional
  description: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

Client updated

Code 404

Client not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing client

URL

/api/client/{client_id}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

client_id: client_id of the client to delete

Success response

Code 200

Client removed

Code 404

Client not found

Scopes management

Get a list of scopes available

Return a list of scopes available

URL

/api/scope/

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

offset: number, the offset to start the list, default 0 limit: number, the maximal number of elements in the list, default 100, if limit is explicitly set to 0, no limit source: string, the instance name to limit the result, if not set, all instances will be used pattern: string, the pattern to filter the result

Success response

Code 200

Content

[{
  name: string, mandatory
  display_name: string, mandatory
  description: string, mandatory
  password_required: boolean, mandatory
  scheme: {
    group_name: [
      {
        scheme_type: module type, string, mandatory
        scheme_name: module name, string, mandatory
        scheme_display_name: module display name, string, mandatory
      }
    ]
  }
}]

Example

[
  {
    name: "scope1",
    display_name: "First scope",
    description: "The first scope",
    password_required: true,
    scheme: {
      group1: [
        {
          scheme_type: "mock",
          scheme_name: "mock1",
          scheme_display_name: "First mock scheme"
        },
        {
          scheme_type: "mock",
          scheme_name: "mock2",
          scheme_display_name: "Second mock scheme"
        }
      ]
    }
  },
  {
    name: "scope2",
    scope: [
      "scope1"
    ],
    enabled: true,
    name: "Second scope",
    confidential: false,
    redirect_uri: [
      "http://another.example.com"
    ]
  }
]

Get a scope

Return the details of a plugin module instance

URL

/api/scope/{name}

Method

GET

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name to return, mandatory source: scope module instance to look for the scope, optional, if not set look on all instances

Success response

Code 200

Content

{
  name: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  enabled: boolean, mandatory
  name: string, optional
  description: string, optional
  confidential: boolean, optional
  other values: string or array of strings, optional, depends on what's returned by the module instance
}

Example

{
  name: "scope1",
  scope: [
    "scope1",
    "scope2"
  ],
  enabled: true,
  name: "First scope",
  confidential: true,
  redirect_uri: [
    "http://example.com/"
  ]
}

Code 404

Scope not found

Add a new scope

URL

/api/scope/

Method

POST

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

source: scope module instance to look for the scope, optional, if not set, the first instance in write mode in order rank will host the new scope

Body Parameters

{
  name: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  password: string, optional, if not set, the scope won't be able to authenticate
  enabled: boolean, optional, default true
  name: string, optional
  description: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

Scope added

Code 400

Error input parameters

Content

A JSON array with the error messages

Update an existing scope

URL

/api/scope/{name}

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the scope to update source: scope module instance to look for the scope, optional, if not set look on all instances

Body Parameters

{
  name: string, mandatory
  scope:[
    scope_value: string, mandatory, array can be empty
  ],
  password: string, optional, if not set, the scope won't be able to authenticate
  enabled: boolean, optional, default true
  name: string, optional
  description: string, optional
  other values: string or array of strings, optional, depends on the module instance
}

Success response

Code 200

Scope updated

Code 404

Scope not found

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete an existing scope

URL

/api/scope/{name}

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

URL Parameters

name: name of the scope to delete

Success response

Code 200

Scope removed

Code 404

Scope not found

API Keys management

Get a list of API keys available

Return a list of API keys available

URL

/api/key/

Method

GET

Security

User with scope g_admin authorized.

URL Parameters

Success response

Code 200

Content

[{
  token_hash: string, mandatory
  counter: integer, mandatory
  username: string, mandatory
  issued_at: integer, mandatory
  issued_for: string, mandatory
  user_agent: string, mandatory
  enabled: boolean, mandatory
}]

Example

[
  {
    "token_hash":"{SHA512}SDb_4UvKcD_4[...]9xSVRunzcJg==",
    "counter":42,
    "username":"admin",
    "issued_at":735700882,
    "issued_for":"1.2.3.4",
    "user_agent":"NCSA_Mosaic/2.0 (Windows 3.1)","enabled":true
  },
  {
    "token_hash":"{SHA512}BOw-ad5HskG11[...]N90_LUcuDnkxdRI5TN_w==",
    "counter":15,
    "username":"operator",
    "issued_at":1466571360,
    "issued_for":"4.3.2.1",
    "user_agent":"Lynx/2.8.9rel.1 libwww-FM/2.14 SSL-MM/1.4.1 GNUTLS/3.6.5",
    "enabled":false
  },
  {
    "token_hash":"{SHA512}_pkJyrClgz66[...]aIgWl8X8L4r0DwG3A==",
    "counter":0,
    "username":"admin",
    "issued_at":1600774400,
    "issued_for":"6.6.6.6",
    "user_agent":"curl/7.20.0 (x86_64-redhat-linux-gnu) libcurl/7.20.0 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5",
    "enabled":true
  }
]

Create a new API key

URL

/api/key/

Method

POST

Security

User with scope g_admin authorized.

Success response

Code 200

Content

{
  key: string, mandatory
}

Example

{
  key: "abcdEFGH1234"
}

Disable an API key

URL

/api/key/{token_hash}

Method

DELETE

URL Parameters

token_hash: identifier of the token to disable

Security

User with scope g_admin authorized.

Success response

Code 200

User authentication

Authenticate a user with password

URL

/api/auth

Method

POST

Body Parameters

{
  username: string, mandatory
  password: string, mandatory
}

Success response

Code 200

User authenticated.

A session cookie is sent to the browser. This cookie will be used by all endpoints that require authentication.

Code 400

Error input parameters

Code 401

Authentication failure

Authenticate a user with an authentication scheme

URL

/api/auth

Method

POST

Body Parameters

{
  username: string, optional for schemes mock, OAuth2 and TLS certificate with scheme storage option, mandatory otherwise
  scheme_type: string, mandatory
  scheme_name: string: mandatory
  value: object, mandatory, content depends on the scheme
}

Success response

Code 200

User authenticated

A session cookie is sent to the browser. This cookie will be used by all endpoints that require authentication.

Code 400

Error input parameters

Code 401

Authentication failure

Get authorized scopes from a scope list for a user

URL

/auth/scheme/

Method

GET

Security

Valid user session.

URL Parameters

scope: list of scopes requested, separated by spaces

Success response

Code 200

Content

{
  "scope_name": { // Name of the scope
    "password_required": boolean, wether the password is required to access this scope
    "schemes":{
      "group_name": [
        {
          "scheme_type": string, module name of the scheme
          "scheme_name": string, module instance name
          "scheme_display_name": string, mudule instance display name
          "scheme_authenticated": boolean, wether this scheme is authenticated for this user on this session
          "scheme_registered": boolean wether this scheme is registered for this user
        }
      ]
    },
    "display_name": string, display name of the scope
    "description":string, description of the scope
    "password_authenticated": boolean, wether this scope is authenticated for this user on this session
    "available": boolean, wether this scope is available for this user
  }
}

Code 400

Error input parameters

Code 401

Authentication failure

Trigger a scheme

URL

/api/auth/scheme/trigger

Method

POST

Body Parameters

{
  username: string, optional for schemes mock, OAuth2 and TLS certificate with scheme storage option, mandatory otherwise
  scheme_type: string, mandatory
  scheme_name: string: mandatory
  value: object, mandatory, content depends on the scheme
}

Success response

Code 200

User authenticated

Code 400

Error input parameters

Code 401

Authentication failure

Change current user with another user authenticated in this session

URL

/api/auth

Method

POST

Body Parameters

{
  username: string, mandatory
}

Success response

Code 200

Current user changed

Code 400

Error input parameters

Code 401

Authentication failure

Grant scopes

Get list of granted scopes for a client by the user

URL

/api/auth/grant/{client_id}/{scope_list}

Method

GET

Security

User with scope g_profile authorized.

URL Parameters

client_id: client_id of the client scope_list: list of scopes separated by a space

Success response

Code 200

Content

{
  "client":{
    "client_id": string, client_id
    "name": string, client name
  },
  "scope":[
    {
      "name": string, scope name
      "display_name": string, scope display name
      "description": string, scope description
      "password_required": boolean, wether this scope has password required to login
      "granted": boolean, wether this scope is granted to this client by this user
    }
  ]
}

Code 401

No enabled authenticated user for this session

Update granted scope for a client by a user

URL

/auth/grant/{client_id}/

Method

PUT

Security

User with scope g_profile authorized.

Body Parameters

{
  "scope": string, scope list granted to this client separated by a comma, set the list empty to remove all grant
}

Success response

Code 200

User updated

Code 400

Error input parameters

Content

A JSON array with the error messages

User profile

Get list of connected profiles

The first element in the returned array is the current user

URL

/api/profile_list

Method

GET

Security

User with scope g_profile authorized.

Success response

Code 200

Content

[
  {
    username: string, mandatory
    scope:[
      scope_value: string, mandatory, array can be empty
    ],
    name: string, optional
    email: string, optional
    other values: string or array of strings, optional, depends on what's returned by the module instance for the profile
  }
]

Code 401

No enabled authenticated user for this session

Update current profile

URL

/api/profile

Method

PUT

Security

User with scope g_profile authorized.

Body Parameters

{
  username: string, mandatory
  name: string, optional
  other values: string or array of strings, optional, depends on what's exptected by the module instance for the profile
}

Success response

Code 200

User updated

Code 400

Error input parameters

Content

A JSON array with the error messages

Change user password for current profile

URL

/api/profile/password

Method

PUT

Security

User with scope g_profile authorized.

Body Parameters

{
  username: string, mandatory, same username as current user
  old_password: string, mandatory
  password: string, mandatory
}

Success response

Code 200

User password updated

Code 400

Error input parameters

Content

A JSON array with the error messages

Delete current profile

URL

/api/profile/

Method

DELETE

Security

User with scope g_profile authorized.

Success response

Code 200

Profile successfully removed

Code 403

The user is not allowed to remove its own profile.

Get list of plugins available

URL

/api/profile/plugin

Method

GET

Security

User with scope g_profile authorized.

Success response

Code 200

Content

[
  {
    "module": string, plugin type
    "name": string, plugin instance name
    "display_name": string, plugin instance display name
  }
]

Code 401

No enabled authenticated user for this session

Get list of granted scopes per clients

URL

/api/profile/grant

Method

GET

Security

User with scope g_profile authorized.

Success response

Code 200

Content

[
  {
    "client_id": string, client_id of the client
    "name": string, client name
    "description": string, client description
    "scope": [
      {
        "name": string, name of the scope
        "display_name": string, display name of the scope
        "description": string, description of the scope
      }
    ]
  }
]

Code 401

No enabled authenticated user for this session

Get sessions for current profile

URL

/api/profile/session

Method

GET

Security

User with scope g_profile authorized.

Success response

Code 200

Content

[
  {
    session_hash: string,
    user_agent: string,
    issued_for: string,
    expiration: string,
    last_login: string,
    enabled: string
  }
]

Code 401

No enabled authenticated user for this session

Disable a session for current profile

URL

/api/profile/session/{session_hash}

Method

DELETE

Security

User with scope g_profile authorized.

Success response

Code 200

Session disabled

Code 401

No enabled authenticated user for this session

Get list of schemes available

URL

/api/profile/scheme

Method

GET

Security

User with scope g_profile authorized.

Success response

Code 200

Content

[
  {
    "module": string, module name of the scheme
    "name": string, module instance name
    "display_name": string, module instance display name
    "expiration": number, duration of an authentication with this scheme
    "max_use": number, number of thime this scheme authenticated can be used in a plugin
    "allow_user_register": boolean, wether the user can register this scheme
    "enabled": boolean
  }
]

Code 401

No enabled authenticated user for this session

Register an auth scheme for current profile

URL

/api/profile/scheme/register/

Method

POST

Security

User with scope g_profile authorized.

Body Parameters

{
  username: string, mandatory
  scheme_type: string, mandatory
  scheme_name: string: mandatory
  value: object, mandatory, content depends on the scheme
}

Success response

Code 200

Scheme registered

Code 400

Error input parameters

Content

A JSON array with the error messages

Code 401

No enabled authenticated user for this session

Get registration on an auth scheme for current profile

URL

/api/profile/scheme/register/

Method

PUT

Security

User with scope g_profile authorized.

Body Parameters

{
  username: string, mandatory
  scheme_type: string, mandatory
  scheme_name: string: mandatory
}

Success response

Code 200

Content

Depends on the scheme

Code 400

Error input parameters

Content

A JSON array with the error messages

Code 401

No enabled authenticated user for this session

Profile delegation

All those endpoints are available for an administrator in order to access and update a user’s profile and its schemes registration

Update profile by delegation

URL

/api/delegate/profile?username=<username>

Method

PUT

Security

Admin with scope g_admin authorized.

Body Parameters

{
  username: string, mandatory
  name: string, optional
  other values: string or array of strings, optional, depends on what's exptected by the module instance for the profile
}

Success response

Code 200

User updated

Code 400

Error input parameters

Content

A JSON array with the error messages

Get sessions for profile by delegation

URL

/api/delegate/profile/session?username=<username>

Method

GET

Security

User with scope g_admin authorized or valid API key header.

Success response

Code 200

Content

[
  {
    session_hash: string,
    user_agent: string,
    issued_for: string,
    expiration: string,
    last_login: string,
    enabled: string
  }
]

Code 401

No enabled authenticated admin for this session

Disable a session for a profile by delegation

URL

/api/delegate/profile/session/{session_hash}?username=<username>

Method

DELETE

Security

User with scope g_admin authorized or valid API key header.

Success response

Code 200

Session disabled

Code 401

No enabled authenticated user for this session

Get list of plugins available by delegation

URL

/api/delegate/profile/plugin?username=<username>

Method

GET

Security

User with scope g_admin authorized or valid API key header.

Success response

Code 200

Content

[
  {
    "module": string, plugin type
    "name": string, plugin instance name
    "display_name": string, plugin instance display name
  }
]

Code 401

No enabled authenticated user for this session

Get list of schemes available by delegation

URL

/api/delegate/profile/scheme?username=<username>

Method

GET

Security

User with scope g_admin authorized or valid API key header.

Success response

Code 200

Content

[
  {
    "module": string, module name of the scheme
    "name": string, module instance name
    "display_name": string, module instance display name
    "expiration": number, duration of an authentication with this scheme
    "max_use": number, number of thime this scheme authenticated can be used in a plugin
    "allow_user_register": boolean, wether the user can register this scheme
    "enabled": boolean
  }
]

Code 401

No enabled authenticated user for this session

Register an auth scheme for a profile by delegation

URL

/api/delegate/profile/scheme/register/?username=<username>

Method

POST

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  username: string, mandatory
  scheme_type: string, mandatory
  scheme_name: string: mandatory
  value: object, mandatory, content depends on the scheme
}

Success response

Code 200

Scheme registered

Code 400

Error input parameters

Content

A JSON array with the error messages

Code 401

No enabled authenticated user for this session

Get registration on an auth scheme for a profile by delegation

URL

/api/delegate/profile/scheme/register/?username=<username>

Method

PUT

Security

User with scope g_admin authorized or valid API key header.

Body Parameters

{
  username: string, mandatory
  scheme_type: string, mandatory
  scheme_name: string: mandatory
}

Success response

Code 200

Content

Depends on the scheme

Code 400

Error input parameters

Content

A JSON array with the error messages

Code 401

No enabled authenticated user for this session

Authentication Scheme APIs

This chapter will describe the specific parameters for the authentication schemes.

The following APIs will be further explained for each scheme:

Register scheme: POST /api/profile/scheme/register/
Get scheme registration: PUT /api/profile/scheme/register/
Trigger scheme: POST /api/auth/scheme/trigger
Authentication using scheme: POST /api/auth

For each APIs, the request and/or response body format will be described. This documentation is an addendum to the generic API documentation above.

Mock authentication scheme

This scheme exist for tests use only, it simply is an authentication scheme that will behave as a normal scheme and implements all the functions to help designing and programming Glewlwyd.

Register scheme

Request body format

{
  username: string, mandatory
  scheme_type: "mock"
  scheme_name: string: mandatory
  value: {
    register: boolean, mandatory
  }
}

Set the parameter value.register to true or false to enable or disable the scheme for the user.

Get scheme registration

Request body format

{
  username: string, mandatory
  scheme_type: "mock"
  scheme_name: string: mandatory
}

Response body format

boolean

The response value will be true or false depending on the scheme registration status.

Trigger scheme

Request body format

{
  username: string, mandatory
  scheme_type: "mock"
  scheme_name: string: mandatory
  value: {} empty object, mandatory
}

Response body format

{
  code: string, will contain the mock value expected to authenticate the user
}

Authentication using scheme

Request body format

{
  username: string, optional
  scheme_type: "mock"
  scheme_name: string: mandatory
  value: {
    username: string, mandatory if omitted below
    code: string, mandatory
  }
}

E-mail OTP authentication scheme

This authentication scheme sends an one-time password to the e-mail of the user and awaits for the user to retype the password in the login page. Therefore, no registration is possible for the user, and the get registration API will return a HTTP status 200 if the user has an e-mail address and 400 otherwise.

Trigger scheme

Request body format

{
  username: string, mandatory
  scheme_type: "email"
  scheme_name: string: mandatory
  value: {} empty object, mandatory
}

Authentication using scheme

Request body format

{
  username: string, mandatory
  scheme_type: "email"
  scheme_name: string: mandatory
  value: {
    code: string, mandatory
  }
}

HOTP/TOTP authentication scheme

Register scheme

Request body format

Request a random secret for a new OTP to the server. The random secret will be returned in a base32 string format.

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    generate-secret: true
  }
}

Delete current OTP setting for the current user

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    type: "NONE"
  }
}

Setup current OTP setting as HOTP

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    type: "HOTP"
    secret: base32 string, mandatory
    moving_factor: positive integer, optional
  }
}

Setup current OTP setting as TOTP

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    type: "TOTP"
    secret: base32 string, mandatory
    time_step_size: non zero positive integer, optional
  }
}

Get scheme registration

Request body format

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
}

Response body format

{
  digits: integer, number of digits required on the authentication code
  issuer: string, will contain the issuer value (a metadata)
  hotp-allow: boolean, set to true if the user is allowed to register a HOTP
  totp-allow: boolean, set to true if the user is allowed to register a TOTP
  type: string, will contain one of the following values: "NONE", "HOTP" or "TOTP"
  secret: string, secret registered if a scheme is registered
  moving_factor: integer
  time_step_size: integer
}

Example, for a TOTP registration:

{
  digits: 6,
  issuer: "https://glewlwyd.tld",
  hotp-allow: true,
  totp-allow: true,
  type: "TOTP",
  secret: "abcd1234===",
  moving_factor: 0
  time_step_size: 30
}

Trigger scheme

N/A

Authentication using scheme

Request body format

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    value: string, mandatory
  }
}

Password authentication scheme

This authentication scheme simply uses the password field of the user - if it’s possible - therefore, this scheme simply has an authentication API implemented

Register scheme

N/A

Get scheme registration

N/A

Trigger scheme

N/A

Authentication using scheme

Request body format

{
  username: string, mandatory
  scheme_type: "otp"
  scheme_name: string: mandatory
  value: {
    password: string, mandatory
  }
}

WebAuthn authentication scheme

This scheme is based on the WebAuthn API.

Register scheme

Request body format

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: string, values available are "new-credential", "register-credential", "remove-credential", "disable-credential", "enable-credential", "edit-credential", "trigger-assertion" or "validate-assertion"
    // Other values depending on the register value
  }
}

Request body format for register: "new-credential"

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "new-credential"
  }
}

Response body format for register: "new-credential"

{
  session: string
  challenge: string
  pubKey-cred-params: array of string, list of public key formats accepted
  attestation-required: boolean, set to false if scheme accepts fmt type "none"
  user: {
    id: string
    name: string
  }
  rpId: string, relaying part id
}

Request body format for register: "register-credential"

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "register-credential",
    session: string, must be the session id sent in the previous "register-credential"
    credential: { // The credential object is returned by the WebAuthn API call `navigator.credentials.create` in the profile page
      rawId: string
      response: {
        clientDataJSON: string
        attestationObject: string
      }
    }
  }
}

Response body format for register: "register-credential"

HTTP Status 200 on success, 401 on error registration, 400 on error parameters, 404 on error in the session id, 500 otherwise

Request body format for register: "remove-credential", register: "disable-credential", register: "enable-credential"

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "remove-credential" || "disable-credential" || enable-credential",
    credential_id: string, must a valid `credential_id` returned by the get_gegister API
  }
}

Response body format for register: "register-credential"

HTTP Status 200 on success, 400 on error parameters, 404 on error in the credential_id, 500 otherwise

Request body format for register: "trigger-assertion"

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "trigger-assertion"
  }
}

Response body format for register: "trigger-assertion"

{
  allowCredentials: array of strings, list of credentials accepted for the user
  session: string
  challenge: string
  user: {
    id: string
    name: string
  }
  rpId: string, relaying part id
}

Request body format for register: "validate-assertion"

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "validate-assertion",
    session: string, must be the session id sent in the previous "register-credential"
    credential: { // The credential object is returned by the WebAuthn API call `navigator.credentials.get` in the profile page
      rawId: string
      response: {
        clientDataJSON: string
        authenticatorData: string
      }
    }
  }
}

Response body format for register: "register-credential"

HTTP Status 200 on success, 401 on error registration, 400 on error parameters, 404 on error in the session id, 500 otherwise

Get scheme registration

Response body format

[
  {
    credential_id: string, identifier of the credential
    name: string, display name of the credential
    created_at: integer, UNIX epoch time where the credential was created
    status: string, status of the credential, values available are "registered" or "disabled"
  }
]

Trigger scheme

Request body format

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {}
}

Response body format

{
  allowCredentials: array of strings, list of credentials accepted for the user, can be a fake list depending on the scheme configuration and the username requested
  session: string
  challenge: string
  user: {
    id: string
    name: string
  }
  rpId: string, relaying part id
}

Authentication using scheme

Request body format

{
  username: string, mandatory
  scheme_type: "webauthn"
  scheme_name: string: mandatory
  value: {
    register: "validate-assertion",
    session: string, must be the session id sent in the previous "register-credential"
    credential: { // The credential object is returned by the WebAuthn API call `navigator.credentials.get` in the profile page
      rawId: string
      response: {
        clientDataJSON: string
        authenticatorData: string
      }
    }
  }
}

TLS Certificate authentication scheme

This authentication scheme is based on TLS certificate authentication. The first level of authentication is provided by the TLS layer deep down the application, therefore a user can’t authenticate with an invalid certificate or a certificate not provided by the configured CA. The scheme module is used to integrate the auth result in Glewlwyd’s authentication process with the session, and is also used to manage registered certificates and emit new certificates if possible.

To successfully authenticate a user in Glewlwyd’s process using the TLS certificate, the used certificate must be valid for the TLS layer AND must be previously registered in the user’s authorized certificate list.

Register scheme

Request body format

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: string, values available are "test-certificate", "upload-certificate", "use-certificate", "request-certificate", "toggle-certificate" or "delete-certificate"
    // Other values depending on the register value
  }
}

Request body format for register: "test-certificate"

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "test-certificate"
  }
}

Response for register: "test-certificate"

HTTP Status 200 on success, 401 on test error, 400 on error parameters, 500 otherwise

Request body format for register: "upload-certificate"

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "upload-certificate"
    x509: string, a X509 certificate in PEM format
  }
}

Response for register: "upload-certificate"

HTTP Status 200 on success, 400 on error parameters, 500 otherwise

Request body format for register: "use-certificate"

This register action uses the certificate currently used in the TLS layer.

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "use-certificate"
  }
}

Response for register: "upload-certificate"

HTTP Status 200 on success, 400 on error parameters, 500 otherwise

Request body format for register: "request-certificate"

This register action returns a PKCS#12 file in DER format encoded in base64 with a random generated password to unlock the provided file.

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "request-certificate"
  }
}

Response body format for register: "request-certificate"

{
  p12: string, PKCS#12 file in DER format encoded in base64
  password: string, used to unlck the PKCS#12 file
}

Request body format for register: "toggle-certificate"

This register action enable or disable a registered certificate

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "toggle-certificate"
    certificate_id: string, a certificate_id registered to the user, mandatory
    enabled: boolean, set the status to enabled or disabled for the certificate
  }
}

Request body format for register: "delete-certificate"

This register action deletes a registered certificate

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    register: "delete-certificate"
    certificate_id: string, a certificate_id registered to the user, mandatory
  }
}

Get scheme registration

Response body format

[
  {
    credential_id: string, identifier of the certificate
    certificate_dn: DN of the certificate
    certificate_issuer_dn: DN Of the issuer of the certificate
    activation: integer, UNIX Epoch time where the certificate was activated
    expiration: integer, UNIX Epoch time where the certificate will expire
    last_used: integer, UNIX Epoch time when the certificate was last succesfully used to authenticate a user, optional
    last_user_agent: string, value of the user-agent when the certificate was last succesfully used to authenticate a user, optional
    enabled: boolean
  }
]

Trigger scheme

N/A

Authentication using scheme

Request body format

{
  username: string, optional if option scheme storage is set, mandatory otherwise
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {}
}

OAuth2/OIDC Client Authentication scheme

Register scheme

Request body format

{
  username: string, mandatory
  scheme_type: "oauth2"
  scheme_name: string: mandatory
  value: {
    action: string, values available are "new", "callback", "delete"
    // Other values depending on the register action value
  }
}

Request body format for action: "new"

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    action: "new",
    provider: string, provider name to register
    complete_url: string, uri for registration completion
  }
}

Response for action: "new"

{
  redirect_to: string, url to the authorization uri
}

HTTP Status 200 on success, 400 on error parameters, 500 otherwise

Request body format for action: "callback"

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    action: "callback",
    provider: string, provider name to register
    state: string
    redirect_to: string
  }
}

HTTP Status 200 on success, 400 on error parameters, 500 otherwise

Request body format for action: "delete"

{
  username: string, mandatory
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    action: "delete",
    provider: string, provider name to delete
  }
}

HTTP Status 200 on success, 400 on error parameters, 500 otherwise

Get scheme registration

Response body format

[
  {
    provider: string, identifier of the provider
    logo_uri: string, uri of the provider logo
    logo_fa: string, fork-awesome logo name
    enabled: boolean
    created_at: null
  }
]

Trigger scheme

Request body format

Get provider list

{
  username: string, mandatory
  scheme_type: "oauth2"
  scheme_name: string: mandatory
  value: {
    provider_list: true
  }
}

Response for provider_list

[
  {
    provider: string, identifier of the provider
    logo_uri: string, uri of the provider logo
    logo_fa: string, fork-awesome logo name
    enabled: boolean
    created_at: null
  }
]

Run authentication flow

{
  username: string, optional
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    provider: string, provider name to authenticate
  }
}

Response for action: "new"

{
  redirect_to: string, url to the authorization uri
}

Authentication using scheme

Request body format

{
  username: string, optional
  scheme_type: "certificate"
  scheme_name: string: mandatory
  value: {
    provider: string, provider name to register
    state: string
    redirect_to: string
  }
}

HTTP Status 200 on success, 400 on error parameters, 500 otherwise