Authentication
This section gives you an in-depth introduction into authenticating with iCL Portal. The complete functionality of iCL Portal is accessible via REST services. For authentication, the OAuth 2.0 bearer token standard is used: In order to access the secured REST services, an access_token has to be acquired from the /token endpoint and then added as a HTTP header to each subsequent request. (Details follow)
All traffic to the token endpoints MUST be secured using HTTPS in order to not compromise your users authentication information.
iCL Portal implements its own permission system, thereby storing the known users and their permissions in a local database (MSSQL). For authentication, it currently supports Forms-based authentication, WS-Federation and authenticating using Salesforce as OAuth authentication server.
Forms-based authentication means that users and passwords are managed by iCL Portal in its local database and the user logs in via a custom login form:
In WS-Federation based authentication, the user is redirected to a specified ADFS (Active Directory Federation Services or Azure Active Directory) authentication server. There she has to enter her credentials and if they are correct, she is redirected to iCL Portal. In that case iCL Portal only stores the users name, but not the passwords. To use this Authentication system, iCL Portal has to be configured to trust the ADFS endpoint and vice versa. The advantage of using WS-Federation authentication is, that once a user is logged-in to ADFS, she can navigate to iCL Portal and are automatically authenticated. (single-sign-on)
Salesforce authentication works similar to WS-Federation but fully follows the OAuth standard. Still, you will have to configure iCL Portal to trust your Salesforce environment and vice versa. The advantage of using Salesforce authentication is, that once a user is logged-in to Salesforce, they can navigate to iCL Portal and are automatically authenticated. (single-sign-on)
When an unauthenticated user navigates to iCL Portal via her browser, they are redirected to the login page where they can choose from all configured authentication mechanisms:
User login using password (Resource Owner Password Credentials flow)​
Forms-based authentication is supported out of the box and does not have to be configured explicitly. For a client application to authenticate itself, it has to post the required authentication parameters to the /token endpoint according to the OAuth 2.0 password_grant flow. The parameters are transmitted form-url-encoded in the body of the HTTP request.
Parameters:
| Name | Type | Required? | Description |
|---|---|---|---|
| grant_type | string | required | has to be "password". |
| username | string | required | only alphanumeric characters. |
| password | string | required | the users password in clear text. (therefore the /token endpoint must not be used with unsecure http, but only https) |
| tenancyName | string | required | the name of the tenant the user belongs to. It normally defaults to “default” but can be configured upon first installation of iCL Portal. |
Example​
POST https://dev.iclportal.com/token HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Content-Length: ...
Accept: */*
Origin: https:// dev.iclportal
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Referer: https://dev.iclportal.com/Account/Login
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
grant_type=password&username=admin&password=Pass@word!&tenancyName=Default
If all goes well, the server responds with 200 OK and sends a JSON object containing the access_token.
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 718
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
{"access_token":"TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1AEaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4zvbO0BoY1AZsWdDDHA","token_type":"bearer","expires_in":1799,"userName":"admin","roles":"Admin,Admin","emailConfirmed":"true","as:client_id":"",".issued":"Tue, 29 Dec 2015 14:34:41 GMT",".expires":"Tue, 29 Dec 2015 15:04:41 GMT"}
This access_token has to be added then to the HTTP header of each subsequent request with the header name “Authorization”, prefixed with “Bearer “:
GET https://dev.iclportal.com/api/account/userinfo?_=1451399681904 HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest
Authorization: Bearer TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis
5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc
3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1A
EaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77
nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4z
vbO0BoY1AZsWdDDHA
Referer: https://dev.iclportal.com
If anything goes wrong (e.g. the user has provided a wrong password), the server responds with HTTP 400 bad request. A more detailed error information can be found in the JSON object in the body of the response:
HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
{"error":"invalid_grant","error_description":"Usernamd or password are incorrect"}
Service client login (Client Credentials flow)​
For service clients, you should use the Client Credentials flow to get an access token.
For this, create a service user with the appropriate permissions that will be used to authenticate API requests.
Then, go to that users settings, open the tab OAuth API tokens and click on Create new.
{
"clientId":"fd52e53d-9b5f-405c-8084-052c8dfe08ac",
"clientSecret":"cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo="
}
Then, you can use these information to get an access token:
POST https://dev.iclportal.com/token HTTP/1.1
Host: dev.iclportal.com
grant_type=client_credentials&client_id=fd52e53d-9b5f-405c-8084-052c8dfe08ac&client_secret=cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo=
If your request is successful, you will get a response like this:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 718
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
{"access_token":"TizVr8StFXx8GueUbGdD9j0V0_jeGT2LMzxZjc8Kw6UOZ2Muy8rZ2guLJCymeU9dJis5lNYPe8HIbh3vfqjZTPa9UvLI4Ixtw6QrSrohQhMpo-ua1Adh5sXSCFWT-FFY-hz_Pp22aXqoAvvDG9cRWwjc3jMUhPrgNq7Xfvj6Xo9B3a-KthzdpET16sQ5I6sjczEdbHUR39a7Z36MQ2_eSpOwWEP2CEN3W1aiS0TDw1AEaBZltyn4fPazdc-Rkn2XwW0Fn26DqL-bY1knbwuyz5JLbNPIno-XUOlz6fSn7e3XPgFefAUGxpU--xyYPspKH0kXO1S6a-_WSdR0qF3euS55P6i-KuPpJNWRAtkR6Xors4NUtRB8hm_V9AbsTW_6F59IZD4kRj77nJxS_4xqDy2VroO0bHh-xLpSFnQ7Aj_uCCu62_wqKjiNRA468bWONXkJOQcEgv6b3fg__ZphtqDS4zvbO0BoY1AZsWdDDHA","token_type":"bearer","expires_in":1799,"userName":"admin","roles":"Admin,Admin","emailConfirmed":"true","as:client_id":"",".issued":"Tue, 29 Dec 2015 14:34:41 GMT",".expires":"Tue, 29 Dec 2015 15:04:41 GMT"}
Using salesforce to authenticate​
In order to use Salesforce as an authentication provider, it has to be configured in the iCL Portal and in Salesforce:
Acessing iCL Portal​
In order for a client application to authenticate using Salesforce, it has to first get all configured authentication providers from iCL Portal from the /api/account/eternalLogins endpoint.
GET https://dev.iclportal.com/api/account/externalLogins?returnUrl=%2F&generateState=false HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: */*
X-Requested-With: XMLHttpRequest`
Don't forget the “returnUrl=%2F” and “generateState=false” parameters, otherwise the server will respond with “404 Not Found”. As the returnurl is only specifying where the browser should redirect to once the user has been authenticated successfully, you can leave it %2f.
The server will respond with all currently configured authentication providers in the HTTP body:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
[{"name":"Salesforce","url":"/api/account/ExternalLogin?provider=Salesforce&response_type=token&client_id=self&redirect_uri=https%3A%2F%2Fdev.iclportal.com%2F&state=SOMELONGSTRING","state":"SOMELONGSTRING","imageUri":null,"imageClass":null}]
Then the returned “url” field has to be used as the endpoint of the GET request in order to obtain an access token. (/api/account/ExternalLogin)
GET https://dev.iclportal.com/api/account/ExternalLogin?provider=Salesforce&response_type=token&client_id=self&redirect_uri=https%3A%2F%2Fdev.iclportal.com%2F&state=SOMELONGSTRING HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
If all goes well, Salesforce will respond with a HTTP 302 redirect to the base-url of iCL Portal, providing the “access_token” as a URL fragment:
HTTP/1.1 302 Found
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: https://dev.iclportal.com/#access_token=rqwfbZ63BNv9s0hUBp9mOYNh2s2Kq2MQQaPMms4Covei-AWm4KLWitfZU8I4BPGBCvCsKN1loGcVNv0VUKSlW4V8HrhF6Ab8BfrLrw7JsEk0cAeArFp3LQ0BNdgzB5bObOZDdw-CoHiFcWLTU79eVR5RU3R9FNBhGdPNgm4b33ZXSQoe0tsjX91a_-wdqcz_c14qysbyX6EzDxBiAO4_WXL2lkXUdjdBPf6fvUKljmHFwKuLPd0xt08EFfPTmRmmJ0TGhb_iOG2dllt3VHwoZCFjRANcUjF1_RNNVbwkKLdpn8aUrq9tTdgBnzL77BBJqm042Sxl4F8nBRvT5YKKGefAjSQ-VSqChYIc1kcgqkPygHIOaLMAiLl2ihcmK4pK3iRJPRsTcFXx5GLfYU4fERLXHkRu9AdQJuLYcMD-vMkgMn5Oh-usXQdSc7sWGRx1WR267j3hYvutrf2YOUEUt41Hh0AA6rapNKcZiMdf3-I&token_type=bearer&expires_in=1800&state=sOTC7dRVB4KdB_UnFZYJz3QzyTuMucJNcS-Hg_l9EL81