Introduction

This is the Authentication component, a RESTful service for identifying users.

To sign up, you can either:

If you’re unsure, we can also help: contact us.

Resources

User

Create Local Account

Anyone can create their own local account.

Example request

http
POST /auth HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk

{"username": "janet test", "password": "changeme", "email": "janet@example.com", "name": "Janet Test", "organisation": "TSI Test"}
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/auth' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"username": "janet test", "password": "changeme", "email": "janet@example.com", "name": "Janet Test", "organisation": "TSI Test"}'
httpie
$ echo '{"username": "janet test", "password": "changeme", "email": "janet@example.com", "name": "Janet Test", "organisation": "TSI Test"}' | http POST 'https://explore.api.aai.ebi.ac.uk/auth' \
    'Content-Type:application/json;charset=UTF-8'
Path Type Description

username

String

Min 5 chars, max 255. Cannot start or end with white-space.

password

String

Min 1 char, max 255.

email

String

Min 1 char, max 255.

name

String

Min 1 char, max 255.

organisation

String

Max 255 chars.

Example response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 40

usr-dd486abb-8ef3-4fb2-9b65-f4ccfe2ba08a

Change password (local account)

You can change the password of the local account by making a PATCH request to /auth, with the password parameter.

Example request

http
PATCH /auth HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic bWU6c2VjcmV0
Host: explore.api.aai.ebi.ac.uk

{"password" : "unicorn"}
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/auth' -i -u 'me:secret' -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"password" : "unicorn"}'
httpie
$ echo '{"password" : "unicorn"}' | http --auth 'me:secret' PATCH 'https://explore.api.aai.ebi.ac.uk/auth' \
    'Content-Type:application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK

Reset password for a local account

Anyone can request resetting password for any local account (e.g. in case of forgetting the password). If a local account exists with given username and email, an email will be sent to the given email address, containing a reset link and an additional secret (PIN). A request without any query parameters will result in sending an email with a reset link pointing to the AAP web application. A request with service query parameter will result in sending an email with a reset link pointing to an external service web application. The external service needs to be configured in AAP.

Example request (link to AAP)

http
POST /reset HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk

{"username" : "happy", "email" : "happy@example.com"}
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/reset' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"username" : "happy", "email" : "happy@example.com"}'
httpie
$ echo '{"username" : "happy", "email" : "happy@example.com"}' | http POST 'https://explore.api.aai.ebi.ac.uk/reset' \
    'Content-Type:application/json;charset=UTF-8'

Example request (link to a service test)

http
POST /reset?service=test HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk

{"username" : "happy", "email" : "happy@example.com"}
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/reset?service=test' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"username" : "happy", "email" : "happy@example.com"}'
httpie
$ echo '{"username" : "happy", "email" : "happy@example.com"}' | http POST 'https://explore.api.aai.ebi.ac.uk/reset?service=test' \
    'Content-Type:application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK

Set password after a reset for a local account

After resetting a password, a user will receive an email with a link to reset password page in AAP web application or external web application. To set a new password, the below endpoint has to be called with the secret reference (extracted from the reset URL) and secret PIN (provided by the user manually) included in the body.

Example request (link to AAP)

http
PUT /reset HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk

{"username":"happy","password":"changed","reference":"rste7428515fb904762bc3ce45d6e0fecad","pin":"abc123"}
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/reset' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"username":"happy","password":"changed","reference":"rste7428515fb904762bc3ce45d6e0fecad","pin":"abc123"}'
httpie
$ echo '{"username":"happy","password":"changed","reference":"rste7428515fb904762bc3ce45d6e0fecad","pin":"abc123"}' | http PUT 'https://explore.api.aai.ebi.ac.uk/reset' \
    'Content-Type:application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK

Create Federated Account

The account will be created automatically on first log in via /sso, capturing the user details directly from the LifeScience Login account.

Update User Registration(Edit local account)

*Authorisation: Only logged in user can edit his/her registration details.

Send '/auth/usr-reference' PUT request with input body to edit your registration details.

You cannot edit other user details. If you try to edit others you will get 'forbidden'(403) error. You are not allowed to update 'username' and 'password', but the rest of the details you can edit.

The system would accept username and password, but it would ignore your changes to persist in the database.

Example request

Path Type Description

username

String

Min 5 chars, max 255. Cannot start or end with white-space.

email

String

Min 1 char, max 255.

name

String

Min 1 char, max 255.

organisation

String

Max 255 chars.

 
{     "username" : "testme",     "email" : "editme@example.com",     "name" : "editme Test",     "organisation" : "TSI Test EditMe" }
http
PUT /auth/usr-fa9777d3-0860-4505-9cf6-87c63a3fcd07 HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk

{     "username" : "testme",     "email" : "editme@example.com",     "name" : "editme Test",     "organisation" : "TSI Test EditMe" }
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/auth/usr-fa9777d3-0860-4505-9cf6-87c63a3fcd07' -i -X PUT \
    -H 'Authorization: Bearer eyJhb...h7HgQ' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{     "username" : "testme",     "email" : "editme@example.com",     "name" : "editme Test",     "organisation" : "TSI Test EditMe" }'
httpie
$ echo '{     "username" : "testme",     "email" : "editme@example.com",     "name" : "editme Test",     "organisation" : "TSI Test EditMe" }' | http PUT 'https://explore.api.aai.ebi.ac.uk/auth/usr-fa9777d3-0860-4505-9cf6-87c63a3fcd07' \
    'Authorization:Bearer eyJhb...h7HgQ' \
    'Content-Type:application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 154

{
  "username" : "testme",
  "email" : "editme@example.com",
  "name" : "editme Test",
  "organisation" : "TSI Test EditMe",
  "accountNonLocked" : true
}

Token

You can get a JWT (Json Web Token) by 2 means, depending on how you signed-up to the AAP: federated or local account. By default, the token is valid for 1 hour, which can be modified via the ttl parameter. The token contains the following claims (not necessarily in that order):

{
  "iss": "https://explore.aai.ebi.ac.uk/sp", (1)
  "jti": "BC45XfIGtB0imhJIvHMJEQ", (2)
  "iat": 1539874710, (3)
  "exp": 1539878310, (4)
  "sub": "usr-fa9777d3-0860-4505-9cf6-87c63a3fcd07", (5)
  "domains": [ (6)
    "self.a domain",
    "self.another domain",
    "aap.token.extend"
  ],
  "email": "test@example.com", (7)
  "nickname": "testme", (8)
  "name": "Test Me" (9)
}

  1. iss (issuer): which AAP instance signed the token

  2. jti: unique identifier for this token, auto-generated

  3. iat (issued at): timestamp when the token was issued

  4. exp (expires at): timestamp when the token expires

  5. sub (subject): the AAP unique reference for this user

  6. domains: the list of domains that the user is a member of

  7. email: the email of the user

  8. nickname: the username of the user; for local accounts, it’s the (human-friendly) username people chose when they created their account with the AAP. For federated accounts, it’s the user opaque reference from the IdP: for LifeScience Login, it’s the eduPersonUniqueID (Person’s unique Id) without the @elixir-europe.org suffix and for EMBL, it’s an anonymised ID of the user (40-char hexadecimal string)

  9. name: the full name of the user

Most JWT libraries will make use of the jti, iat, exp claims themselves, and you will need to configure them with the certificate to verify the token signature: You can get this certificate directly from the URI in iss, which is a shortcut to retrieving the PEM certificate.

We expect you will make use of the following claims:

  • sub when making further requests to the API that require the user reference.

  • domains for your application’s own authorisation rules. When using the security module of the AAP Java Client, you can use these domain names as the Spring Security roles (for example in @PreAuthorise, @PostAuthorise, etc).

The following claims might be useful, depending on the requirement of your application:

  • name for displaying back to the user

  • email to contact the user

  • nickname is the value that’s expected on the AAP web application, when adding a user to a domain where you are a manager.

Federated Account

The /sso endpoint should be used to get a token for a federated account. This will start a series of redirects that will lead the user to their chosen credential provider. It will only work successfully when using an HTTP Client that supports both redirects and cookies (like a browser).

When the user finishes the authentication process with their chosen credential provider (after entering their username / password in the relevant steps and answering any relevant consent form), there are more redirects ending up in a token being served, like:

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 680

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46dGVzdDplbWJsOmViaTp0c2k6ZGlzcG9zYWJsZSIsImp0aSI6Im52MEN1T1c5Z1FnNEFNVGx4YXV0VHciLCJpYXQiOjE2ODMyOTM3NjEsInN1YiI6InVzci1mYTk3NzdkMy0wODYwLTQ1MDUtOWNmNi04N2M2M2EzZmNkMDciLCJlbWFpbCI6ImphbmV0QGV4YW1wbGUuY29tIiwibmlja25hbWUiOiJ0ZXN0bWUiLCJuYW1lIjoiSmFuZXQgVGVzdCIsImRvbWFpbnMiOltdLCJleHAiOjE2ODMyOTczNjF9.AWj9yUI9_GIe9LW_bdj4UlYgtFsYY3BW06E5VBa2vkdqnl1OLzT3R5flW9-Rnz18WpR7iPpP7tJ7XnXAZuAqK_jSlAPwNCNP3z0-OPDwZ21HebEDRuGfA5uyxvrbc_Pol0EamER9LM_cR4yWsUCT6-FDexIlFfJOUN9sgkbfESWqU2kZOyNg1oTufIJ1MBptp-OCgcMjp1qfBgyswI2TvCwGXfKGgEPP0hrwvqlfjfdWJsMlt2regn0R9I2KgxjXrlSXgvbdy9fk4e2wZShCqQjjSgvY6-NNtvZMjcrEqhITV2nNofaVVUmUadxL1fbC7zjrZWQ5WVYMZJxjRZSwVw

from Attribute

The from attribute helps integrate the AAP into javascript single page applications. If supplied, the response will be an HTML page with a javascript script that will push the token to the opening page. For security reasons, because both pages are on separate hostnames, this push will only work if both the application and script are aware of each other. This is achieved by the AAP knowing which hostname the request is coming from, so we can include the reference back when we push.

From the point of view of the single page application, it needs to implement a window.onMessage(event) handler to receive the token, which will be the event.data.

Local Account

The /auth endpoint should be used to get a token for local accounts, supplying the AAP username & password using HTTP Basic.

Example request

http
GET /auth HTTP/1.1
Authorization: Basic bWU6c2VjcmV0
Host: explore.api.aai.ebi.ac.uk
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/auth' -i -u 'me:secret'
httpie
$ http --auth 'me:secret' GET 'https://explore.api.aai.ebi.ac.uk/auth'

Example response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 680

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46dGVzdDplbWJsOmViaTp0c2k6ZGlzcG9zYWJsZSIsImp0aSI6Im52MEN1T1c5Z1FnNEFNVGx4YXV0VHciLCJpYXQiOjE2ODMyOTM3NjEsInN1YiI6InVzci1mYTk3NzdkMy0wODYwLTQ1MDUtOWNmNi04N2M2M2EzZmNkMDciLCJlbWFpbCI6ImphbmV0QGV4YW1wbGUuY29tIiwibmlja25hbWUiOiJ0ZXN0bWUiLCJuYW1lIjoiSmFuZXQgVGVzdCIsImRvbWFpbnMiOltdLCJleHAiOjE2ODMyOTczNjF9.AWj9yUI9_GIe9LW_bdj4UlYgtFsYY3BW06E5VBa2vkdqnl1OLzT3R5flW9-Rnz18WpR7iPpP7tJ7XnXAZuAqK_jSlAPwNCNP3z0-OPDwZ21HebEDRuGfA5uyxvrbc_Pol0EamER9LM_cR4yWsUCT6-FDexIlFfJOUN9sgkbfESWqU2kZOyNg1oTufIJ1MBptp-OCgcMjp1qfBgyswI2TvCwGXfKGgEPP0hrwvqlfjfdWJsMlt2regn0R9I2KgxjXrlSXgvbdy9fk4e2wZShCqQjjSgvY6-NNtvZMjcrEqhITV2nNofaVVUmUadxL1fbC7zjrZWQ5WVYMZJxjRZSwVw

Common Attributes

ttl

You can request a shorter or longer token using the ttl (time to live) query parameter. It specifies the validity of the token, in minutes. Anyone can request a shorter token for example 30 minutes validity token and slightly longer token up to 3 hours(180 minutes validity). To get this slightly longer token lifetime user doesn’t require any special membership.

Only members of aap.token.extend can request longer tokens. There is currently no maximum on the length of the token.

If a user is not part of aap.token.extend and request a token longer than the default, they will receive a token up to 3 hours validity.

Token default validity is one hour.

Refresh

With the /token endpoint, you can request an updated AAP token, without having to re-authenticate. The new token has the same expiry as the token you used to make the request, but with updated user registration details & updated set of domains.

Example request

http
GET /token HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Host: explore.api.aai.ebi.ac.uk
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/token' -i \
    -H 'Authorization: Bearer eyJhb...h7HgQ'
httpie
$ http GET 'https://explore.api.aai.ebi.ac.uk/token' \
    'Authorization:Bearer eyJhb...h7HgQ'

Example response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 687

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46dGVzdDplbWJsOmViaTp0c2k6ZGlzcG9zYWJsZSIsImp0aSI6Ilc1RDNkNkRvNE9qdDVZd21OLWtPTWciLCJpYXQiOjE2ODMyOTM3NjEsInN1YiI6InVzci1mYTk3NzdkMy0wODYwLTQ1MDUtOWNmNi04N2M2M2EzZmNkMDciLCJlbWFpbCI6ImphbmV0QGV4YW1wbGUuY29tIiwibmlja25hbWUiOiJ0ZXN0bWUiLCJuYW1lIjoiSmFuZXQgVGVzdCIsImRvbWFpbnMiOlsiZm9vIl0sImV4cCI6MTY4MzI5NzM2MX0.6XuYowufk3ZzRh0DqGcnn30wv43ugtEDWynAutPQxFjWSn1xKPo3CSicuh_BZI53mVZUvQeNMdZYNlrfUISHNXIwP5DIfzU6t5DotcvU8ogohujuKhdO3W4ume4sIhSGB9_WGSNpNpQukFogkSHlxTkdHi_MGrhwCwTZgdJMKZXg-BzCzzMtPJCkvuq2jK9lS0i-8ipfU57HlAEB58i9CIH3IzbrVGJyIC7OuWqtXz60aBc6i-1ZKru9UjbnQsvaNpo5y9-c7FJbtwLTLMLjcr659ky5PM1lTMBfQDglBZmUwr66s7oYJMWvn89mnFLzBgamWIK1C4iA-v5xVqQaKQ

Meta

The meta resource exposes the x509 certificate (aka public key) that should be used to verify the signature of the token. It comes in two formats: PEM (base64 encoded text) or DER (binary).

Retrieve x509 certificate as PEM

Example request

http
GET /meta/public.pem HTTP/1.1
Host: explore.api.aai.ebi.ac.uk
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/meta/public.pem' -i
httpie
$ http GET 'https://explore.api.aai.ebi.ac.uk/meta/public.pem'

Example response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1262

-----BEGIN CERTIFICATE-----
MIIDeTCCAmGgAwIBAgIEWGRGCzANBgkqhkiG9w0BAQsFADBtMQswCQYDVQQGEwJVSzEQMA4GA1UE
CBMHRW5nbGFuZDESMBAGA1UEBxMJQ2FtYnJpZGdlMREwDwYDVQQKEwhFTUJMLUVCSTEMMAoGA1UE
CxMDVFNJMRcwFQYDVQQDEw5OZXZlciBUcnVzdCBNZTAeFw0xNjA3MjUxMDE4MDdaFw0xNjEwMjMx
MDE4MDdaMG0xCzAJBgNVBAYTAlVLMRAwDgYDVQQIEwdFbmdsYW5kMRIwEAYDVQQHEwlDYW1icmlk
Z2UxETAPBgNVBAoTCEVNQkwtRUJJMQwwCgYDVQQLEwNUU0kxFzAVBgNVBAMTDk5ldmVyIFRydXN0
IE1lMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7BiefgLwGxEl+Y/RaXjSGzLs4IMl
NHUjttGOCg4ZaN29GmSMsg3/PqpLlh5Lh7fW1Xe/STiKK5lwBXD8FvrIUcHus2YSEkXxZ++lJ5gX
QiWhC8tNpmDcay9YsyneqFteuFH1eY73YcVikDcLTbZyyS1qAa3h6d2ELk1hd+4a4ByLZ5PUUCg8
ec02N70XvchNHg2meaTswOGTwaJ6SWc9/zQ82JW5T2c37VbWNGgW0whSjR+UxI3T+4uqSWMANYoa
AFu9zEDa1eyuUwdEe1zIRaH9MHKQGdBmrz2y6y1Vsrcdp9iaDqfjqdK6DWpnS/GbKWXB3IZ72huz
hf2ikFl5iwIDAQABoyEwHzAdBgNVHQ4EFgQUGTMHENcSn1Pky3O0uGenaH3wMpUwDQYJKoZIhvcN
AQELBQADggEBAOocGg866B7D/6MB6IUW9JiagvcFH8YhkFDylFm11/hUCqH9w+CY/Oodle3JXpLF
E6KzHQKBz4ptXiV3NtBl2FM3Xt/xg0bPjde1OMMIDeNAJwBNpX7xzxXWWEYSv3N6IiP+jyCDVhf5
NkmVF3hYbq2e+ex1H69Y97gGiQQBcHZ5ZJsYvMgoOjIkAK/b3FtC4CFslm4/tD3hzYCdh/WPnDyW
GIPGUcNllEhvyvDmxhnJ4LdwrVlt/Mj5oaOjGEefhjtvRrPZlpPlps9GJxRbpwEcmAnZ7DsBZowW
KLegsYTGlZiF8LhmWR3RCQKcmr0X4CgmYMPr+TG42xuD7ENhWLs=
-----END CERTIFICATE-----

Retrieve x509 certificate as DER

Example request

http
GET /meta/public.der HTTP/1.1
Host: explore.api.aai.ebi.ac.uk
curl
$ curl 'https://explore.api.aai.ebi.ac.uk/meta/public.der' -i
httpie
$ http GET 'https://explore.api.aai.ebi.ac.uk/meta/public.der'

Example response

Omitted (binary file)