## Authentication

### Authentication challenge

In typical REST style, calling the App Orchestration APIs without specifying either a valid session token or authentication information will result in a `401 Unauthorized` response. For example, a request / response may look like this:

Request:

        GET https://srv01.my.com/cam/api/Tenants HTTP/1.1
        Host: srv01.my.com

Response:

        HTTP/1.1 401 Unauthorized
        WWW-Authenticate: Negotiate
        WWW-Authenticate: NTLM
        WWW-Authenticate: Basic realm="my.com"
        [...]

Note that App Orchestration supports multiple methods of authentication. These are described below.

If the calling program is running inside of a browser (for example, if it is a JavaScript client-side application), the `401` status code and `WWW-Authenticate` headers are usually intercepted by the browser and the response never makes it to your application. If you wish to handle authorization within this type of application, it is necessary to change the authorization challenge so that the browser will not intercept it. App Orchestration supports this through the use of a custom header on the request:

Request:

        GET https://srv01.my.com/cam/api/Tenants HTTP/1.1
        Host: srv01.my.com
        X-Custom-Auth-Challenge: true
        [...]

Response:

        HTTP/1.1 400 Bad Request
        X-WWW-Authenticate: Basic realm="my.com"
        [...]

If your application requires this, set the `X-Custom-Auth-Challenge` header on every request, and be prepared to handle authorization challenges whenever the `X-WWW-Authenticate` header is in the response.

### Windows Integrated authentication

This allows callers to authenticate automatically using their current identity, without passing any explicit credentials to the server. To use this method of authentication, the caller's machine must be running on a Windows-based operating system, and be located within a domain that is trusted by the App Orchestration server's domain.

There are libraries in various programming languages available to help with Windows Integrated authentication, but the most typical is to use this mode from a .NET-based client, as the .NET Framework has built-in support for this kind of authentication.

One very useful application of this form of authorization is when the calling program is run by a user who is an App Orchestration administrator. Using Windows Integrated authentication, the calling program does not need to know the user's password.

Example C# code:

    var handler = new HttpClientHandler {UseDefaultCredentials = true};
    var client = new HttpClient(handler);

Even when credentials are explicitly known by the calling program, Windows Integrated authentication allows an extra layer of security. In this case, the client knows the credentials, but the authentication is negotiated without ever passing the credentials over-the-wire to the server. To do this in C#, you can attach an explicit `NetworkCredential` to the `HttpClientHandler` object.

Example C# code:

    var userName = @"DOMAIN\joeadmin";
    var password = new SecureString();
    "P@ssw0rd".ToList().ForEach(password.AppendChar);
    var handler = new HttpClientHandler {Credentials = new NetworkCredential(userName, password)};
    var client = new HttpClient(handler);

To prevent Cross-Site Request Forgery attacks, App Orchestration will not return any results or perform any action on the first Windows-authenticated request. Instead, whenever Windows Integrated authentication is negotiated, App Orchestration creates a session and responds with status `205 Reset Content`. This informs the caller to issue the request again, providing the appropriate Session Token and Anti-Forgery Token.

### Basic authentication

This allows any caller, regardless of operating system or environment, to authenticate using explicit credentials.

To use this form of authorization, when the calling application receives an authorization challenge it should issue the request again while including an `Authorization: Basic [encodedCredential]` header. The encoded credential is formed by combining the administrator's full user name and password, with a colon (":") in the middle; for example:

        DOMAIN\joeadmin:P@ssw0rd

This string is then Base-64 encoded, resulting in a request such as:

        GET https://srv01.my.com/cam/api/Tenants HTTP/1.1
        Host: srv01.my.com
        Authorization: Basic RE9NQUlOXGpvZWFkbWluOlBAc3N3MHJk

Even when using Basic authentication, App Orchestration creates a Session Token and Anti-Forgery Token for the caller. It is highly recommended to use those for further requests, to prevent the overhead of the full authorization process on every call.

Unlike Windows Integrated authentication, App Orchestration will return results and/or perform actions on the first Basic-authenticated request.