Back to top

Authentication REST Interface

The following resources do not require the Authorization header:

  • /token

  • /sign_request

  • /clients

  • /certs

  • register

All other resources require authentication via access token or basic authentication with your client ID as username and your client secret as password.

All requests must include the access token in the Authorization Header, except the /token resource.

OAuth2 Informations

Get some general informations about this OAuth2 identity provider.

Client list

GET/clients

Get a list of active clients.

Example URI

GET https://auth.example.com/oauth2/clients
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "clientId": "adfiowerj9",
    "name": "Samply MDR",
    "description": "The central Samply MDR",
    "redirectUrl": "https://mdr.samply.de/",
    "type": "MDR"
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "clientId": {
        "type": "string",
        "description": "The unique client identifier"
      },
      "name": {
        "type": "string",
        "description": "The name of the client"
      },
      "description": {
        "type": "string",
        "description": "A simple description of the client"
      },
      "redirectUrl": {
        "type": "string",
        "description": "One or more redirect URLs separated by ','"
      },
      "type": {
        "type": "string",
        "description": "One of 'MDR', 'FORMREPOSITORY', 'UNDEFINED', the client type"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Keys

GET/certs

Get the public keys used in Samply.Auth.

Example URI

GET https://auth.example.com/oauth2/certs
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "keyType": "RSA",
    "use": "sig",
    "keyId": "1",
    "n": "MEF43AB10F...",
    "e": "AQAB",
    "derFormat": "MIICIjANBgkqhkiG9w0BAQE...",
    "base64DerFormat": "MIICIjANBgkqhkiG9w0BAQEFAA..."
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "keyType": {
        "type": "string",
        "description": "The key type, one of 'RSA', 'EC'"
      },
      "use": {
        "type": "string",
        "description": "The usage of this key, one of 'sig' (singing), 'enc' (encryption)"
      },
      "keyId": {
        "type": "string",
        "description": "The key ID"
      },
      "n": {
        "type": "string",
        "description": "the base64url encoded modulus of the RSA key"
      },
      "e": {
        "type": "string",
        "description": "the base64url encoded public exponent of the RSA key"
      },
      "derFormat": {
        "type": "string",
        "description": "The base64url+DER encoded public key"
      },
      "base64DerFormat": {
        "type": "string",
        "description": "The base64+DER encoded public key"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

OAuth2

Get an access token

POST/token

Get a new access token, id token and refresh token.

Example URI

POST https://auth.example.com/oauth2/token
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Body
{
  "client_id": "abc",
  "client_secret": "ghz",
  "code": "adfwerwer",
  "refresh_token": "eysdfre",
  "signature": "afsdfwre"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "eysdfwer234wr.sfdsdfwer....",
  "id_token": "eysdfwerfdg",
  "refresh_token": "eysdfertwt"
}
Schema
{
  "type": "object",
  "properties": {
    "access_token": {
      "type": "string",
      "description": "The signed JWT access token"
    },
    "id_token": {
      "type": "string",
      "description": "The signed JWT ID token, that contains informations about the user, like his real name"
    },
    "refresh_token": {
      "type": "string",
      "description": "The signed refresh token, that you can use to get a new access token."
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  400
HideShow

No payload or the refresh token is not valid

Response  401
HideShow

Your client has been disabled (code) or the user has been disabled (signature)

Response  403
HideShow

The provided refresh token is not valid

Response  404
HideShow

The client ID, client secret or code are unknown or the sign request is unknown

Get a sign request

POST/sign_request

Get a code that you can sign to get an access token.

Example URI

POST https://auth.example.com/oauth2/sign_request
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Body
{
  "keyId": {},
  "sha512Hash": "abdc545"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "code": "asdwer",
  "expirationDate": [
    {
      "element": "string",
      "content": "123234234"
    }
  ],
  "algoritm": "SHA512withRSA"
}
Schema
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The code that you must sign"
    },
    "expirationDate": {
      "type": "number",
      "description": "The expiration date of this sign request"
    },
    "algoritm": {
      "type": "string",
      "description": "The signature algorithm that you must use"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  404
HideShow

The key could not be found.

Get data about the token

GET/tokeninfo

Example URI

GET https://auth.example.com/oauth2/tokeninfo
Request
HideShow
Headers
Authorization: Bearer eyfswer....
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "expirationDate": [
    {
      "element": "string",
      "content": "123123"
    }
  ],
  "subject": "https://test.de/users/5",
  "scope": [
    "mdr",
    "openid",
    "login",
    "formrepository"
  ],
  "nonce": "asdfsdfwr",
  "notBeofre": [
    {
      "element": "string",
      "content": "123123"
    }
  ],
  "issuer": "https://auth.samply.de"
}
Schema
{
  "type": "object",
  "properties": {
    "expirationDate": {
      "type": "number",
      "description": "Expiration date of the access token"
    },
    "subject": {
      "type": "string",
      "description": "The subject of the access token"
    },
    "scope": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The list of scopes from the access token"
    },
    "nonce": {
      "type": "string",
      "description": "A random string"
    },
    "notBeofre": {
      "type": "number",
      "description": "The date before the access token must be rejected"
    },
    "issuer": {
      "type": "string",
      "description": "The issuer of the access token"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  403
HideShow

The given access token is not valid

Get data about the user

GET/userinfo

Example URI

GET https://auth.example.com/oauth2/userinfo
Request
HideShow
Headers
Authorization: Bearer eyfswer....
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "real_name": "Max Mustermann",
  "contact_information": "Phone: 01234/5678",
  "external_label": "DKTK",
  "email": "max@mustermann.de",
  "email_verified": true,
  "id": "https://auth.samply.de/users/453",
  "locations": [
    {
      "id": "UNIMAINZ",
      "name": "Universitätsmedizin Mainz",
      "description": "Der Standort Universitätsmedizin Mainz im DKTK",
      "contact": "Ansprechpartner John Doe, 42-123456"
    }
  ],
  "roles": [
    {
      "identifier": "TEST_ROLE",
      "name": "Test Rolle",
      "description": "Nur eine Rolle zum Testen"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "real_name": {
      "type": "string",
      "description": "The real name of the user"
    },
    "contact_information": {
      "type": "string",
      "description": "The contact informations"
    },
    "external_label": {
      "type": "string",
      "description": "The label of the external identity provider"
    },
    "email": {
      "type": "string",
      "description": "The users email address"
    },
    "email_verified": {
      "type": "boolean",
      "description": "If true, the user has verified his email address"
    },
    "id": {
      "type": "string",
      "description": "The users ID. Unique in the Samply.Auth instance."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier for this location"
          },
          "name": {
            "type": "string",
            "description": "The name of the location"
          },
          "description": {
            "type": "string",
            "description": "The description of the location"
          },
          "contact": {
            "type": "string",
            "description": "The contact information"
          }
        }
      },
      "description": "The list of locations this user belongs to"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "The identifier for the role"
          },
          "name": {
            "type": "string",
            "description": "The name of the role"
          },
          "description": {
            "type": "string",
            "description": "The description of this role"
          }
        }
      },
      "description": "The list of roles that this user is a member of"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  403
HideShow

The given access token is not valid

Search for users

GET/users/search{?query}

Example URI

GET https://auth.example.com/oauth2/users/search?query=Max
URI Parameters
HideShow
query
string (required) Example: Max

The name or email address that you what to search for

Request
HideShow
Headers
Authorization: Bearer eyfswer....
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "real_name": "Max Mustermann",
    "contact_information": "Phone: 01234/5678",
    "external_label": "DKTK",
    "email": "max@mustermann.de",
    "email_verified": true,
    "id": "https://auth.samply.de/users/453"
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "real_name": {
        "type": "string",
        "description": "The real name of the user"
      },
      "contact_information": {
        "type": "string",
        "description": "The contact informations"
      },
      "external_label": {
        "type": "string",
        "description": "The label of the external identity provider"
      },
      "email": {
        "type": "string",
        "description": "The users email address"
      },
      "email_verified": {
        "type": "boolean",
        "description": "If true, the user has verified his email address"
      },
      "id": {
        "type": "string",
        "description": "The users ID. Unique in the Samply.Auth instance."
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Get data about a specific user

GET/users/{userId}

Example URI

GET https://auth.example.com/oauth2/users/5
URI Parameters
HideShow
userId
integer (required) Example: 5

The ID of the user. Usually the last part of the subject

Request
HideShow
Headers
Authorization: Bearer eyfswer....
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "real_name": "Max Mustermann",
  "contact_information": "Phone: 01234/5678",
  "external_label": "DKTK",
  "email": "max@mustermann.de",
  "email_verified": true,
  "id": "https://auth.samply.de/users/453",
  "locations": [
    {
      "id": "UNIMAINZ",
      "name": "Universitätsmedizin Mainz",
      "description": "Der Standort Universitätsmedizin Mainz im DKTK",
      "contact": "Ansprechpartner John Doe, 42-123456"
    }
  ],
  "roles": [
    {
      "identifier": "TEST_ROLE",
      "name": "Test Rolle",
      "description": "Nur eine Rolle zum Testen"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "real_name": {
      "type": "string",
      "description": "The real name of the user"
    },
    "contact_information": {
      "type": "string",
      "description": "The contact informations"
    },
    "external_label": {
      "type": "string",
      "description": "The label of the external identity provider"
    },
    "email": {
      "type": "string",
      "description": "The users email address"
    },
    "email_verified": {
      "type": "boolean",
      "description": "If true, the user has verified his email address"
    },
    "id": {
      "type": "string",
      "description": "The users ID. Unique in the Samply.Auth instance."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier for this location"
          },
          "name": {
            "type": "string",
            "description": "The name of the location"
          },
          "description": {
            "type": "string",
            "description": "The description of the location"
          },
          "contact": {
            "type": "string",
            "description": "The contact information"
          }
        }
      },
      "description": "The list of locations this user belongs to"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "The identifier for the role"
          },
          "name": {
            "type": "string",
            "description": "The name of the role"
          },
          "description": {
            "type": "string",
            "description": "The description of this role"
          }
        }
      },
      "description": "The list of roles that this user is a member of"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Get data about a specific user identified by its subject

GET/user{?sub}

Example URI

GET https://auth.example.com/oauth2/user?sub=https:/auth.samply.de/users/4
URI Parameters
HideShow
sub
string (required) Example: https://auth.samply.de/users/4

The subject identifier

Request
HideShow
Headers
Authorization: Bearer eyfswer....
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "real_name": "Max Mustermann",
  "contact_information": "Phone: 01234/5678",
  "external_label": "DKTK",
  "email": "max@mustermann.de",
  "email_verified": true,
  "id": "https://auth.samply.de/users/453",
  "locations": [
    {
      "id": "UNIMAINZ",
      "name": "Universitätsmedizin Mainz",
      "description": "Der Standort Universitätsmedizin Mainz im DKTK",
      "contact": "Ansprechpartner John Doe, 42-123456"
    }
  ],
  "roles": [
    {
      "identifier": "TEST_ROLE",
      "name": "Test Rolle",
      "description": "Nur eine Rolle zum Testen"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "real_name": {
      "type": "string",
      "description": "The real name of the user"
    },
    "contact_information": {
      "type": "string",
      "description": "The contact informations"
    },
    "external_label": {
      "type": "string",
      "description": "The label of the external identity provider"
    },
    "email": {
      "type": "string",
      "description": "The users email address"
    },
    "email_verified": {
      "type": "boolean",
      "description": "If true, the user has verified his email address"
    },
    "id": {
      "type": "string",
      "description": "The users ID. Unique in the Samply.Auth instance."
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier for this location"
          },
          "name": {
            "type": "string",
            "description": "The name of the location"
          },
          "description": {
            "type": "string",
            "description": "The description of the location"
          },
          "contact": {
            "type": "string",
            "description": "The contact information"
          }
        }
      },
      "description": "The list of locations this user belongs to"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "The identifier for the role"
          },
          "name": {
            "type": "string",
            "description": "The name of the role"
          },
          "description": {
            "type": "string",
            "description": "The description of this role"
          }
        }
      },
      "description": "The list of roles that this user is a member of"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Location

Get all locations

GET/locations

Get a list of all currently available locations.

Example URI

GET https://auth.example.com/oauth2/locations
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "UNIMAINZ",
    "name": "Universitätsmedizin Mainz",
    "description": "Der Standort Universitätsmedizin Mainz im DKTK",
    "contact": "Ansprechpartner John Doe, 42-123456"
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "The identifier for this location"
      },
      "name": {
        "type": "string",
        "description": "The name of the location"
      },
      "description": {
        "type": "string",
        "description": "The description of the location"
      },
      "contact": {
        "type": "string",
        "description": "The contact information"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  403
HideShow

No access token provided

Role

Get all roles

GET/roles

Get a list of all currently available roles.

Example URI

GET https://auth.example.com/oauth2/roles
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "identifier": "TEST_ROLE",
    "name": "Test Rolle",
    "description": "Nur eine Rolle zum Testen"
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "The identifier for the role"
      },
      "name": {
        "type": "string",
        "description": "The name of the role"
      },
      "description": {
        "type": "string",
        "description": "The description of this role"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  403
HideShow

No access token provided

Get data for a specific role

GET/roles/{roleIdentifier}

Get all details for a specific role

Example URI

GET https://auth.example.com/oauth2/roles/TEST_ROLE
URI Parameters
HideShow
roleIdentifier
string (required) Example: TEST_ROLE

The identifier of the role.

Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "identifier": "TEST_ROLE",
  "name": "Test Rolle",
  "description": "Nur eine Rolle zum Testen",
  "members": [
    {
      "real_name": "Max Mustermann",
      "contact_information": "Phone: 01234/5678",
      "external_label": "DKTK",
      "email": "max@mustermann.de",
      "email_verified": true,
      "id": "https://auth.samply.de/users/453"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "The identifier for the role"
    },
    "name": {
      "type": "string",
      "description": "The name of the role"
    },
    "description": {
      "type": "string",
      "description": "The description of this role"
    },
    "members": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "real_name": {
            "type": "string",
            "description": "The real name of the user"
          },
          "contact_information": {
            "type": "string",
            "description": "The contact informations"
          },
          "external_label": {
            "type": "string",
            "description": "The label of the external identity provider"
          },
          "email": {
            "type": "string",
            "description": "The users email address"
          },
          "email_verified": {
            "type": "boolean",
            "description": "If true, the user has verified his email address"
          },
          "id": {
            "type": "string",
            "description": "The users ID. Unique in the Samply.Auth instance."
          }
        }
      },
      "description": "The members of this role"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  403
HideShow

No access token provided

Registration

Register your Registry

POST/register

Register your Registry, Bridgehead or Share Client at Samply.Auth. In the end this request creates a new user in Samply.Auth.

Example URI

POST https://auth.example.com/oauth2/register
Request
HideShow
Headers
Content-Type: application/json
Accept: application/json
Body
{
  "base64EncodedPublicKey": "MIIsdfwer",
  "description": "OSSE",
  "email": "admin@osse.rare",
  "name": "Registry for Rare diseases"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "userId": [
    {
      "element": "string",
      "content": "345"
    }
  ],
  "keyId": [
    {
      "element": "string",
      "content": "12313"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "userId": {
      "type": "number",
      "description": "Your user ID"
    },
    "keyId": {
      "type": "number",
      "description": "Your public key ID"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  409
HideShow

A user with this email address already exists

Response  400
HideShow

No payload or the given key is not a base64+DER formatted public RSA key

Response  501
HideShow

The registration has been disabled

Generated by aglio on 17 May 2016