Skip to content
This repository has been archived by the owner on Jan 21, 2022. It is now read-only.

Latest commit

 

History

History
200 lines (150 loc) · 6.83 KB

Login-APIs.md

File metadata and controls

200 lines (150 loc) · 6.83 KB
Raw

Login Server APIs

Overview

The Login Server:

  • is separate from the UAA but needs to be connected to one via HTTP(S)
  • provides SSO for web applications in the Cloud Foundry platform
  • manages and provides a branded HTML UI for authentication and OAuth approval
  • provides some other features via JSON APIs

Login Form: GET /login

Request: GET /login?error={error}
Response Body: form with all the relevant prompts
Response Codes: 200 - Success

Form Login: POST /login.do

Browser POSTs to /login.do with user credentials (same as UAA). Login Server returns a cookie that can be used to authenticate future requests (until the session expires or the user logs out).

Logout: GET /logout.do

The Login Server is a Single Sign On server for the Cloud Foundry platform (and possibly user apps as well), so if a user logs out he logs out of all the apps. Users need to be reminded of the consequences of their actions, so the recommendation for application authors is to

  • provide a local logout feature specific to the client application and use that to clear state in the client
  • on the success page for that logout provide a link to the Login Server logout endpoint with a message telling the user what will happen if he clicks it
  • provide a redirect in the link to the logout endpoint (see below) so that the user come back to a familiar place when logged out, otherwise he will just get the logged out success page from the Login Server

Request: GET /logout.do?redirect=http://myclient/loggedout
Request Headers: Cookie: JSESSIONID=8765FDUAYSFT7897
Response Codes:

200 - OK (if no redirect supplied)
302 - FOUND (if redirect supplied)

OAuth2 Endpoints

The standard authorize and token endpoints are available on the Login Server. They are passed through the request to the UAA, getting JSON responses from the UAA and re-rendering them if the user requested HTML.

Start Authorization: GET /oauth/authorize

Client applications usually send a redirect to User's browser with the request URI appropriate to the Client. Exactly the same as the UAA, but the response is rendered differently.

Request: example

GET /oauth/authorize?response_type=code&
  redirect_uri=https://myclient/callback&
  client_id=myclient&
  state=RANDOM

The request must be authenticated as a user, so usually a session cookie (JSESSIONID) is required, having been obtained previously through the Login page.

Obtain Authorization Code: POST /oauth/authorize

Exactly the same as the UAA. When user approves the browser sends user_oauth_approval=true (or false) and the Login Server sends back an authorization code (if one was previously requested).

Token Endpoint: POST /oauth/token

Obtain an access token, typically either with an authorization code or client credentials. Exactly the same as the UAA.

Login Info: GET /login

Reports basic information about the build (version and git commit id) and also passes through the information about prompts from the UAA. Unauthenticated.

Healthz: GET /healthz

Returns "ok" in the response body if the server is up and running

Varz: GET /varz

Reports basic management information about the Login Server and the JVM it runs in (memory usage etc.). Secured with HTTP Basic authentication using credentials that are advertised on NATS in Cloud Foundry (for a standalone instance the default is varz:varzclientsecret).

Request: GET /varz
Response Body:

{
  "type": "Login",
  "links": {
    "JMImplementation": "http://localhost:8080/uaa/varz/JMImplementation",
    "spring.application": "http://localhost:8080/uaa/varz/spring.application",
    "com.sun.management": "http://localhost:8080/uaa/varz/com.sun.management",
    "Catalina": "http://localhost:8080/uaa/varz/Catalina",
    "env": "http://localhost:8080/uaa/varz/env",
    "java.lang": "http://localhost:8080/uaa/varz/java.lang",
    "java.util.logging": "http://localhost:8080/uaa/varz/java.util.logging"
  },
  "mem": 19173496,
  "memory": {
    "verbose": false,
    "non_heap_memory_usage": {
      "max": 184549376,
      "committed": 30834688,
      "init": 19136512,
      "used": 30577744
    },
    "object_pending_finalization_count": 0,
    "heap_memory_usage": {
      "max": 902299648,
      "committed": 84475904,
      "init": 63338496,
      "used": 19173496
    }
  },
  "spring.profiles.active": []
}

Autologin

For user-facing account management UIs (e.g. portal) that need to set or reset users' passwords it is convenient to be able to log them in immediately, rather than waiting for them to come back to the Login Server and enter the new password explicitly.

  1. Client POSTs user credentials to /autologin

  2. Login Server responds with autologin code (short-lived, one-time)

  3. Client builds redirect URI to Login Server /authorize endpoint (normal OAuth2 auth code flow) appending the code

  4. Client sends redirect to User

  5. User's browser initiates auth code flow

  6. Login Server redeems autologin code and exchanges it for an authenticated user (as if the user had authenticated with the Login Server manually)

  7. User's browser now has SSO cookie for Login Server, and remains logged in for the duration of that session.

Obtain Autologin Code: POST /autologin

Gets a short-lived code that can be exchanged for an authentication at the Login Server /oauth/authorize UI. The client authenticates itself with its secret using an HTTP Basic header.

Request: POST /autologin
Request Body: Form encoded user credentials

username=<username>&password=<password>

Request Headers:

Authorization: Basic <...>

Response Body:

{ "code"="aiuynklj", "path"="/oauth/authorize" }

By default the password is required and is checked using the login.do endpoint at the UAA, but could be made optional or changed to other authentication credentials with a configuration change in the Login Server (by adding a different AuthenticationManager to the AutologinController).