Canonical Identity Provider Documentation

Transcription

1 Canonical Identity Provider Documentation Release Canonical Ltd. December 14, 2018

2

3 Contents 1 API General considerations Rate limiting Standard response codes Standard response format Standard errors New format Errors Resources Account Token OAuth token Password reset token Macaroon Requests Registration Examples Login Examples Password reset Examples HTTP Routing Table 31 i

4 ii

5 Contents: Contents 1

6 2 Contents

7 CHAPTER 1 API General considerations SSL only JSON UTF-8 Rate limiting All API requests are rate limited. Upon reaching this limit, a HTTP response with status code 429 is returned. The body of such responses will be like: "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please try again later.", "extra": "Retry-After": 53 Standard response codes Success: 200 OK 201 Created Errors: 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 409 Conflict 3

8 415 Unsupported Media Type Standard response format Success: HTTP/ OK "href": " "openid": "openid123", " ": "displayname": "Foo Bar Baz", "status": "NEW", "verified": true, " s": [ "href": " ] Error: HTTP/ BAD REQUEST "code": "INVALID_DATA", "message": "Invalid request data.", "extra": "displayname": "Field required" Standard errors The following generic error codes are currently defined: INVALID_DATA: Input data failed to validate. Error status code 400. The extra field includes the names of the fields that failed to validate, and a reason why they failed. See the relevant documentation for errors specific to each api. New format Errors The Snap Packages API uses conventional HTTP response codes to indicate success or failure of an API request. 4 Chapter 1. API

9 In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing) and codes in the 5xx range indicate an error with our servers. Here is detailed the format for API responses that end in error. This applies to all the 4xx responses, but also to some 5xx ones (if possible, the client should be prepared to handle 5xx responses with no informational body). Note that this structure format does not apply to 2xx and 3xx responses, as those are note errors. Important: Not all API endpoints are migrated yet to this new error format Format An error response body will contain the following field: error_list: a list of one or several items (never empty), each item described by... message: a text in English describing the error that happened, ready to show to the user. code: a short (but representative) string indicating concisely the error; it s aimed for clients to take specific actions and react to the problem. See below for the list of existing codes. Additionally and for backwards compatibility reasons, some other fields may be present as well, but are considered deprecated and will be removed in the near future. No status or success indication is returned inside the response body, the client should react properly to the received HTTP return code according to its well stablished semantics. Codes These are the codes used in the response and their meanings: account-not-ready: the account is deactivated, suspended or account is not validated. bad-request: there is a problem in the structure of the request. field-required: the field in the request can t be empty or null. internal-server-error: some unexpected problem server side; this will be the code in all 5xx cases. invalid-credentials: the credentials for the authentication are not valid (e.g.: the username or password is not correct). invalid-data: the data is incorrect or corrupt. permission-required: the macaroon authorization is missing in the received request or not enough for it to be fulfilled. resource-not-found: one or more fields are included to specify a resource, but it is not found in the Store. resource-not-ready: the request actions on a resource that is not ready yet for that purpose; normally something else would need to be done first on the resource before this request can be repeated. twofactor-required: two-factor authentication is required for this request but was not provided. user-not-ready: the user is not ready to issue the received request; normally some actions would need to be done in the user account before repeating the request New format Errors 5

10 Examples A simple error: "error_list": [ "message": "The field 'expiration' must be an integer", "code": "invalid-field" ] A multiple error: "error_list": [ "message": "The 'foo' field is required", "code": "missing-field", "message": "The 'bar' field is required", "code": "missing-field", "message": "The 'baz' field must not be empty", "code": "invalid-field" ] 6 Chapter 1. API

11 CHAPTER 2 Resources Account Data structure An Account resource provides the following fields: href Link to the account resource itself. openid Claimed user open id suffix. preferred Preferred address. displayname Display name for the user. status Status of the account. Possible values are: verified Not activated Active Deactivated (by user) Suspended (by admin) True if the account is verified (atm, it checks if the user has a validated address). s List of addresses associated to the user, each one with an href field linking to the corresponding resource, and a boolean verified field that indicates if the has been verified or not. The list will have at the most 10 results, and they will be ordered from last created to oldest. tokens List of oauth tokens associated to the user, each one with an href field linking to the corresponding token resource, and a name field that holds the name given to the token at creation time. 7

12 The list will have at the most 10 results, and they will be ordered from last updated (last used) to less used. Use cases Create an account POST /api/v2/accounts Creates a new account Form Parameters user s address password user s password (min 8 chars) displayname user s name creation_source a string describing source of user creation (optional) captcha_id (optional) captcha_solution (optional) create_captcha (optional, defaults to True) Status Codes 201 Created account created 401 Unauthorized captcha required Errors The errors are returned as a json-encoded dict with keys: code: code name, see below for the list of names (e.g. ALREADY_REGISTERED) message: error explanation (e.g. The address is already registered) extra: specific to each error (optional) INVALID_DATA: The provided data is not valid or incomplete. Error status code 400. The extra attribute in the response will include all the fields that failed validation, like: "code": "INVALID_DATA", "message": "Invalid request data", "extra": "password": ["Field required"], "displayname": ["Field required"], " ": ["Field required"] ALREADY_REGISTERED: This address is already registered. The error uses a 409 code, indicating a conflict. The extra field includes: the that was used to register 8 Chapter 2. Resources

13 CAPTCHA_FAILURE: Failed response to captcha challenge. Error status code 403. This error has one field in the extra attribute. capture_message: the error message returned by recaptcha. CAPTCHA_REQUIRED: A captcha challenge is required to complete the request. Error status code 401. If create_captcha is True (the default), this error will include two fields in the extra attribute. If False, extra will be empty. image_url: a link to an image containing the captcha challenge to be answered captcha_id: the identifier for this specific challenge (which should be sent back along with the user provided response) The consumer should present the user with the image referred by the image_url attribute, and collect a response from the user. The consumer should then retry the request, including two extra parameters: captcha_id (as provided in the error response) captcha_solution: the user provided response to the captcha challenge CAPTCHA_ERROR: The recaptcha service is down or not working properly. Error status code 502. This error has the following fields. recaptcha_reason text reason for the error recaptcha_status_code * the http code returned by the recaptcha service recaptcha_body * http body returned by the recaptcha service * These fields will be empty for non http network errors (like connection refused ) Examples Request: POST /api/v2/accounts HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": "foo@example.com", "password": "thepassword", "displayname": "Foo Bar Baz" If captcha is required POST /api/v2/accounts HTTP/1.1 Host: login.ubuntu.com Accept: application/json 2.1. Account 9

14 " ": "password": "thepassword", "displayname": "Foo Bar Baz", "captcha_id": "some-captcha-id", "captcha_solution": "the solution" Response: HTTP/ CREATED Vary: Accept Location: /api/v2/accounts/openid123 "href": " "openid": "openid123", "preferred ": "displayname": "Foo Bar Baz", "status": "NEW", "verified": false, " s": [ "href": " ] If captcha is required HTTP/ UNAUTHORIZED Vary: Accept "code": "CAPTCHA_REQUIRED", "message": "Captcha validation required.", "extra": "image_url": " "captcha_id": "some-captcha-id" An Ubuntu SSO account can have one or more s linked to it. addresses can have a verified or unverified status, depending on whether the owner completed the verification process for each address or not. An account s can also be the preferred address, which will be a verified address if there is such, otherwise it will be the l address the user created the account with. 10 Chapter 2. Resources

15 Authentication This endpoint requires every request to be OAuth signed with a token belonging to the account owning the that is being operated on. The OAuth token can be obtained following the documentation at the OAuth token resource. Example of OAuth signing code, assuming an existing account foo@example.com with password password: import json import requests from requests_oauthlib import OAuth1 SSO_ROOT_URL = ' SSO_API_URL = SSO_ROOT_URL + 'api/v2/' = 'foo@example.com' data = ' ': , 'password': 'password', 'token_name': 'Doc test' response = requests.post( SSO_API_URL + 'tokens/oauth', json=data, headers='accept': 'application/json') credentials = response.json() auth = OAuth1(credentials['consumer_key'], credentials['consumer_secret'], credentials['token_key'], credentials['token_secret']) response = requests.get( SSO_API_URL + ' s/' + , auth=auth, headers='accept': 'application/json') print(response.json()) Use cases Obtain details GET /api/v2/ s/< address> Obtain details for a given address Form Parameters verified whether the was verified or not date_created date when was linked to the account address href link to this resource Status Codes 200 OK ok 401 Unauthorized OAuth signature is not valid Errors INVALID_DATA: Provided is not correct. Error status code

16 Examples Request: POST HTTP/1.1 Host: login.ubuntu.com Accept: application/json Response: HTTP/ OK Location: " ": "verified": true, "href": "/api/v2/ s/foo%40example.com", "date_created": " T14:16:41" If the OAuth signature is not correct: HTTP/ UNAUTHORIZED "code": "INVALID_CREDENTIALS", "message": "Your /password isn't correct.", "extra": Token Ubuntu SSO uses tokens of different kinds for different aspects of the service. Currently it knows about the following types of tokens OAuth token Password reset token Macaroon OAuth token An OAuth token represents a token used to sign requests using the OAuth 1.0a spec. Data structure consumer_key consumer_secret 12 Chapter 2. Resources

17 token_key token_secret token_name date_created date_updated Use cases Create an oauth token POST /api/v2/tokens/oauth Creates a new OAuth token Form Parameters user s address password user s password token_name a name for the token otp one-time password (optional) Status Codes 200 OK existing token returned 201 Created token created 401 Unauthorized invalid credentials or otp password required 403 Forbidden invalid otp provided 403 Forbidden account is suspended or inactive 403 Forbidden invalidated A consumer requesting an authentication token must provide a token name. This name will be used by the user to identify the token when doing token management. The recommended scheme for token names is application_namedevice_name. This allows a user to easily identify which tokens belong to which application or to which device. For example they may wish to revoke all tokens for a particular application across their devices, or revoke all tokens on a particular device. If a token name is requested that already exists (for this user) then the existing token will be returned (status code 200) instead of a new one being created (status code 201). If an otp (one-time-password) is provided then it will be checked against any two factor devices registered for the account. If the otp does not match any devices then a 403 will be returned. If an otp is required for the account, but not sent, then a 401 will be returned. Errors INVALID_CREDENTIALS: Provided /password is not correct. Error status code OAuth token 13

18 ACCOUNT_SUSPENDED: Account has been suspended. Error status code 403. ACCOUNT_DEACTIVATED: Account has been deactivated. Error status code _INVALIDATED: This address has been invalidated. Error status code 403. TWOFACTOR_REQUIRED: 2-factor authentication required. Error status code 401. TWOFACTOR_FAILURE: The provided 2-factor key is not recognised. Error status code 403. PASSWORD_POLICY_ERROR: The user s password doesn t comply with the security constraints in force for the account. It must be reset via the web. Error status code 403. The extra field includes: location: the domain to visit via the web to reset the password reason: the reason why the password doesn t comply with the policy TOO_MANY_REQUESTS: Too many requests from the same IP address. Error status code 429. Examples Request: POST /api/v2/tokens/oauth HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": "foo@example.com", "password": "thepassword", "token_name": "the-name" If 2-factor authentication is required: 14 Chapter 2. Resources

19 POST /api/v2/tokens/oauth HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": "password": "thepassword", "token_name": "the-name", "otp": "123456" Response: HTTP/ CREATED Location: /api/v2/tokens/oauth/the-key "href": " "token_key": "token-key", "token_secret": "token-secret", "token_name": "token-name", "consumer_key": "consumer-key", "consumer_secret": "consumer-secret" "date_created": " :43:23", "date_updated": " :43:23" If credentials don t match: HTTP/ UNAUTHORIZED "code": "INVALID_CREDENTIALS", "message": "Your /password isn't correct.", "extra": If 2-factor authentication is required: HTTP/ UNAUTHORISED "code": "TWOFACTOR_REQUIRED", "message": "This account requires 2-factor authentication.", "extra": Password reset token A password reset token represents a token used to request a password reset. This token will be generated and an will be sent to the user s preferred address including a value that has to be provided when specifying the new password Password reset token 15

20 Data structure Use cases Create a password reset token POST /api/v2/tokens/password Creates a new password reset token Form Parameters user s address Status Codes 201 Created token created 403 Forbidden account suspended 403 Forbidden account deactivated 403 Forbidden can not reset password 403 Forbidden invalidated 403 Forbidden too many tokens A consumer requesting a password reset token must provide an address. This address will be used to look up the user s account in order to send the user an containing a token that must be provided when setting the new password. To prevent spamming unknowing users by sending multiple password reset s, only a maximum amount of nonconsumed tokens will be allowed to exist at any given time. When such limit is reached, attempting to create a new token will result in an error response. Errors ACCOUNT_SUSPENDED: Account has been suspended. Error status code 403. ACCOUNT_DEACTIVATED: Account has been deactivated. Error status code _INVALIDATED: This address has been invalidated. Error status code 403. CAN_NOT_RESET_PASSWORD: Can not reset password. Error status code Chapter 2. Resources

21 TOO_MANY_TOKENS: Too many non-consumed tokens exist. Further token creation is not allowed until existing tokens expire or are consumed. Error status is 403. Examples Request: POST /api/v2/tokens/password HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": Response: HTTP/ CREATED Location: /api/v2/tokens/password/the-key " ": If too many tokens exist: HTTP/ FORBIDDEN "code": "TOO_MANY_TOKENS", "message": "Too many non-consumed tokens exist. Further token creation is not allowed until existin "extra": Macaroon A macaroon is a bearer token with fine-grained constraints. See the original paper for details. Ubuntu SSO issues discharge macaroons, which can be bound to macaroons issued by other cooperating services to prove the user s identity. Use cases Issue a discharge macaroon POST /api/v2/tokens/discharge Issues a new discharge macaroon 2.6. Macaroon 17

22 Form Parameters user s address password user s password caveat_id the caveat ID addressed to Ubuntu SSO from the macaroon that is to be discharged otp one-time password (optional) Status Codes 200 OK macaroon issued 400 Bad Request invalid request data 401 Unauthorized invalid credentials or otp password required 403 Forbidden invalid otp provided 403 Forbidden account is suspended or inactive 403 Forbidden invalidated 403 Forbidden password does not meet security constraints The service that issued the macaroon that this discharge is to be bound to should have included a caveat in that macaroon addressed to Ubuntu SSO. To issue an appropriate discharge macaroon, the caller must extract the ID of this caveat. This can be done in Python as follows: from pymacaroons import Macaroon def extract_caveat_id(macaroon_raw): macaroon = Macaroon.deserialize(macaroon_raw) for caveat in macaroon.caveats: if caveat.location == 'login.ubuntu.com': return caveat.caveat_id else: raise ValueError('No login.ubuntu.com caveat found') If an otp (one-time-password) is provided then it will be checked against any two factor devices registered for the account. If the otp does not match any devices then a 403 will be returned. If an otp is required for the account, but not sent, then a 401 will be returned. Errors INVALID_CREDENTIALS: Provided /password is not correct. Error status code 401. ACCOUNT_SUSPENDED: Account has been suspended. Error status code 403. ACCOUNT_DEACTIVATED: Account has been deactivated. Error status code Chapter 2. Resources

23 _INVALIDATED: This address has been invalidated. Error status code 403. TWOFACTOR_REQUIRED: 2-factor authentication required. Error status code 401. TWOFACTOR_FAILURE: The provided 2-factor key is not recognised. Error status code 403. PASSWORD_POLICY_ERROR: The user s password doesn t comply with the security constraints in force for the account. It must be reset via the web. Error status code 403. The extra field includes: location: the domain to visit via the web to reset the password reason: the reason why the password doesn t comply with the policy TOO_MANY_REQUESTS: Too many requests from the same IP address. Error status code 429. Examples Request: POST /api/v2/tokens/discharge HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": "foo@example.com", "password": "thepassword", "caveat_id": "\"secret\": \"thesecret\", \"version\": 1" If 2-factor authentication is required: POST /api/v2/tokens/discharge HTTP/1.1 Host: login.ubuntu.com Accept: application/json " ": "foo@example.com", "password": "the-password", "caveat_id": "\"secret\": \"the-secret\", \"version\": 1", "otp": "123456" 2.6. Macaroon 19

24 Response: HTTP/ OK "discharge_macaroon": "the-macaroon" If credentials don t match: HTTP/ UNAUTHORIZED "error_list": [ "code": "invalid-credentials", "message": "Provided /password is not correct." ] If 2-factor authentication is required: HTTP/ UNAUTHORIZED "error_list": [ "code": "twofactor-required", "message": "2-factor authentication required." ] Refresh a discharge macaroon POST /api/v2/tokens/refresh Refreshes a discharge macaroon Form Parameters discharge_macaroon the serialized macaroon to be refreshed Status Codes 200 OK macaroon refreshed 400 Bad Request invalid request data 401 Unauthorized discharge macaroon does not verify 403 Forbidden account is inactive Discharge macaroons are time-limited and must eventually be refreshed. The need for this will be indicated by an error response from the cooperating service. When this happens, the caller should send the old discharge macaroon to this endpoint, which will issue a refreshed version if the original credentials are still valid. 20 Chapter 2. Resources

25 Among other reasons, the discharge macaroon may fail to verify if the user s password has changed since it was issued. In this case, the caller must request a new discharge macaroon. Errors INVALID_CREDENTIALS: The provided discharge macaroon is invalid, or the user s password has changed since the discharge macaroon was issued. Error status code 401. ACCOUNT_DEACTIVATED: Account has been deactivated. Error status code 403. Examples Request: POST /api/v2/tokens/refresh HTTP/1.1 Host: login.ubuntu.com Accept: application/json "discharge_macaroon": "the-old-macaroon" Response: HTTP/ OK "discharge_macaroon": "the-new-macaroon" If the user s password has changed: HTTP/ UNAUTHORIZED "error_list": [ "code": "invalid-credentials", "message": "Provided /password is not correct." ] 2.6. Macaroon 21

26 Requests A controller resource to operate on OAuth requests. This endpoint performs OAuth signature validation to allow external services to authenticate users via OAuth signed requests. Valid Tokens are those obtained from the OAuth token resource. Data structure is_valid: boolean If the OAuth signature provided is valid, a few extra fields are returned: identifier: identifier for the account owning the OAuth token used to sign the request account_verified: whether the account owning the OAuth token used to sign the request is verified or not Use cases Validate an OAuth signature POST /api/v2/requests/validate Validates an OAuth-signature. Form Parameters http_url the target url that was originally OAuth signed by a client http_method the target http method that was originally OAuth signed authorization the OAuth Authorization header resulting from OAuth signing the http request to the url http_url using method http_method Status Codes 200 OK always, with a json-encoded body returning if signature is valid or not This method does not require authentication, and returns whether the given OAuth signature is valid for the given http_url and http_method. If the authorization field is not present, the OAuth signature is expected to be present in http_url as part of the query string. Examples Request: POST /api/v2/requests/validate HTTP/1.1 Host: login.ubuntu.com Accept: application/json "http_url": " "http_method": "GET", "authorization": "OAuth realm='some client', oauth_version='1.0', oauth_signature='oitso7pakzxodfsq 22 Chapter 2. Resources

27 Response: If signature is valid: HTTP/ OK "is_valid": true, "identifier": "64we8bn", "account_verified": true If signature is not valid: HTTP/ OK "is_valid": false 2.7. Requests 23

28 24 Chapter 2. Resources

29 CHAPTER 3 Registration Registration is performed by creating an Account resource. Refer to Create an account for details. Examples curl -d '" ": "foo@example.com", "password": "thepassword", "displayname": "Foo Bar Baz"' \ -H '' \ -X POST \ 25

30 26 Chapter 3. Registration

31 CHAPTER 4 Login Login is performed by creating an OAuth token resource. Refer to Create an oauth token for details. Examples curl -d '" ": "foo@example.com", "password": "thepassword", "token_name": "foo-desktop"' \ -H '' \ -X POST \ 27

32 28 Chapter 4. Login

33 CHAPTER 5 Password reset Password reset is initiated by creating a Password reset token resource. The user will receive an containing a token, which is to be provided alongside with the new password to complete the reset procedure. Refer to Create a password reset token for details. Examples curl -d '" ": "foo@example.com"' \ -H '' \ -X POST \ 29

34 30 Chapter 5. Password reset

35 HTTP Routing Table /api GET /api/v2/ s/< address>, 11 POST /api/v2/accounts, 8 POST /api/v2/requests/validate, 22 POST /api/v2/tokens/discharge, 17 POST /api/v2/tokens/oauth, 13 POST /api/v2/tokens/password, 16 POST /api/v2/tokens/refresh, 20 31