-
Notifications
You must be signed in to change notification settings - Fork 6
Security
The API only supports TLS/SSL secured https protocol.
All API resources respect role, user and data visibility (customer account, project, team, manager, employee) based restrictions defined by the each company's PlanMill Power users for the back-end service and any user interface maintained by PlanMill.
These restrictions may cause the responses to be different for same resource based on whose userid and API key are used to sign the requests.
If some user doesn't have right to see for example project 123 at all, API will return an error with response code 401 (Unauthorized).
If user has right to see the project, but not all information for it, he will get a JSON response containing those attributes he is allowed to see, but those attributes he isn't allowed to see are not contained at all.
If you need to handle other users private information like timereports absences, expenses etc. you must have enough access rights in your API user account.
For example handling time reports for other users requires so called "secretary" rights and viewing absences requires HR -access to absences. Expenses requires your user account to see/edit all projects and to have project space expenses view -access.
Authorization based restrictions are valid also for creating, updating and deleting resources.
OAuth 2.0 protocol introduces the HTTP header "Authorization" for authentication and authorization to PlanMill API endpoints. The request header value is a randomised string token. Current implementation only supports the authorization and the client credentials flow.
The access token lifetime is configured to be 60 minutes. Refresh tokens do not expire and only one refresh token can exist per client and per user.
To read more about the standard follow this link : http://oauth.net/2/ .
Standard Authorization URI for PlanMill is located in the https://online.planmill.com/{instance}/api/oauth2/authorize endpoint.
Required parameters "client_id", "redirect_uri" and "response_type".
Optional parameters "scope" and "state".
Standard Token URI for PlanMill is located in the https://online.planmill.com/{instance}/api/oauth2/token endpoint.
Required parameters "client_id", "client_secret" and "grant_type".
Optional parameter "state".
OAuth 2.0 usage requires the clients to be registered to the server, which provides the client with a client identifying string and a client secret. The registration also requires a redirect URI or multiple URIs in comma separated string format.
The registration process can be done under the https://online.planmill.com/{instance}/api/registrations.jsp page.
The page will also provide the public RSA key to verify OpenID Connect extension specified signed JSON Web Token "id_token" .
More information about the OpenID Connect and JWTs can be found under these urls: http://openid.net/connect/ , https://jwt.io/ .
Refresh and access tokens can be revoked through the /api/oauth2/revoke endpoint that requires query parameters "client_id", "client_secret" and "token".
To support verification and inspection of access tokens, a non-standard token info endpoint was implemented. It can be accessed through HTTP GET protocol to /api/oauth2/tokeninfo endpoint.
The request requires query parameters "client_id", "client_secret" and "access_token". Response is in JSON format that includes the user, the scope and the audience and expiration in seconds bound to the token.
Also a userinfo endpoint was added. It can be accessed through HTTP GET request to /api/oauth2/userinfo endpoint and requires a Authorization header with the access token. It will provide information about the user, who is bound to the token and all scopes available to the user.
Scopes are currently implemented as the PlanMill system's access rights and the scope parameter, that is provided during an OAuth 2.0 authorization request or during a refresh token grant, is checked against the user's current access rights.
Implementation example in Java language is available here: https://github.com/planmill/api-data-helper
Please use Oauth2 -authentication if possible.
API is secured with secure information in a HTTP-header in each request. Information is similar to data used in OAuth 1.0 or digest.
The authentication header contains the API user's id, a client generated nonce, timestamp and a signature. Note that the Authentication header is base-64 encoded (SHA256)
More information and an example about the authentication header can be found here: Authentication example
Real service checks authentication data, e.g. uniqueness of nonce. For more details see each endpoints documentation for authentication header values.
For quick prototyping you can use the https://online.planmill.com/yourinstancename/api/keytest.jsp -page (requires authentication) which generates a ready-made authentication header which you can copy paste to your API client.