anchor.diff:  }
   ----
   
  -== User
  -This API is still in development and subject to change.
  -
  -A User represents an actor in the system.
  -
  -Sample User:
  -----
  -{
  -    "kind": "User",
  -    "apiVersion": "v1beta1",
  -    "metadata": {
  -        "name": "ldap:bob",
  -        "uid": "123df313-b404-4efe-9856-fdfb13a2a005",
  -        "selfLink": "/osapi/v1beta1/users/ldap:bob",
  -        "creationTimestamp": "2015-01-01T01:01:01-00:00"
  -    }
  -}
  -----
  -
  -== UserIdentityMapping
  -This API is still in development and subject to change.
  -
  -A UserIdentityMapping maps an identity (consisting of an identity provider and username) to a User.
  -
  -Sample UserIdentityMapping:
  -----
  -{
  -    "kind": "UserIdentityMapping",
  -    "apiVersion": "v1beta1",
  -    "metadata": {
  -        "name": "ldap:bob",
  -        "selfLink": "/osapi/v1beta1/userIdentityMappings/ldap:bob",
  +== User objects
  +
  +=== Identity
  +When a user logs into OpenShift, they do so using a configured identity provider  (see Identity Providers in the Configuring Authentication topic).
  +The provider determines the user's identity, and provides that information to OpenShift.
  +
  +OpenShift then looks for a UserIdentityMapping for that Identity:
  +
  +* If the Identity already exists, but is not mapped to a User, login fails
  +* If the Identity already exists, and is mapped to a User, the user is given an OAuthAccessToken for the mapped User
  +* If the Identity does not exist, an Identity, User, and UserIdentityMapping are created, and the user is given an OAuthAccessToken for the mapped User
  +
  +Sample Identity:
  +----
  +{
  +    "kind": "Identity",
  +    "apiVersion": "v1",
  +    "metadata": {
  +        "name": "anypassword:bob", <1>
  +        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe",
           "resourceVersion": "1",
           "creationTimestamp": "2015-01-01T01:01:01-00:00"
       },
  +    "providerName": "anypassword", <2>
  +    "providerUserName": "bob", <3>
  +    "user": {
  +        "name": "bob", <4>
  +        "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe" <5>
  +    }
  +}
  +----
  +<1> Identity name must be in the form providerName:providerUserName
  +<2> The name of the identity provider
  +<3> The name that uniquely represents this identity in the scope of the identity provider
  +<4> The name of the user this identity maps to
  +<5> The UID of the user this identity maps to
  +
  +=== User
  +A User represents an actor in the system. Users are granted permissions by adding roles to users or to their groups 
  +(see link:../../admin_guide/manage_authorization_policy.html#managing-role-bindings[Managing Role Bindings]).
  +
  +User objects are created automatically on first login, or can be created via the API.
  +
  +Sample User:
  +----
  +{
  +    "kind": "User",
  +    "apiVersion": "v1",
  +    "metadata": {
  +        "name": "bob", <1>
  +        "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe",
  +        "resourceVersion": "1",
  +        "creationTimestamp": "2015-01-01T01:01:01-00:00"
  +    },
  +    "identities": [
  +        "anypassword:bob" <2>
  +    ],
  +    "fullName": "Bob User", <3>
  +    "groups": [
  +        "mygroup" <4>
  +    ]
  +}
  +----
  +<1> The user name, used when adding roles to a user
  +<2> Names of Identity objects that map to this user. May be `null` or empty for users that cannot log in.
  +<3> Optional display name of user
  +<4> Groups the user belongs to
  +
  +=== UserIdentityMapping
  +A UserIdentityMapping maps an Identity to a User.
  +
  +Creating, updating, or deleting a UserIdentityMapping modifies the corresponding fields on the Identity and User objects.
  +
  +An Identity can only map to a single User (so that logging in as a particular identity unambiguously determines the User).
  +
  +A User can have multiple Identities mapped to it (so multiple login methods can identify the same User).
  +
  +Sample UserIdentityMapping:
  +----
  +{
  +    "kind": "UserIdentityMapping",
  +    "apiVersion": "v1",
  +    "metadata": {
  +        "name": "anypassword:bob", <1>
  +        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe",
  +        "resourceVersion": "1"
  +    },
       "identity": {
  -        "metadata": {
  -            "name": "ldap:bob",
  -            "creationTimestamp": "2015-01-01T01:01:01-00:00"
  -        },
  -        "provider": "ldap",
  -        "userName": "bob"
  +        "name": "anypassword:bob",
  +        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe"
       },
       "user": {
  -        "metadata": {
  -            "name": "ldap:bob",
  -            "uid": "123df313-b404-4efe-9856-fdfb13a2a005",
  -            "creationTimestamp": "2015-01-01T01:01:01-00:00"
  -        }
  +        "name": "bob",
  +        "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe"
       }
   }
   ----
  -
  -== OAuthClient
  -This API is still in development and subject to change.
  -
  +<1> UserIdentityMapping name matches the mapped Identity name
  +
  +== OAuth objects
  +
  +=== OAuthClient
   An OAuthClient represents an OAuth client, as described in
   https://tools.ietf.org/html/rfc6749#section-2[RFC 6749, section 2].
   
  
positive.code: ----
  {
      "kind": "OAuthClientAuthorization",
      "apiVersion": "v1beta1",
      "metadata": {
          "name": "ldap:bob:openshift-web-console",
          "selfLink": "/osapi/v1beta1/oAuthClientAuthorizations/ldap:bob:openshift-web-console",
          "resourceVersion": "1",
          "creationTimestamp": "2015-01-01T01:01:01-00:00"
      },
      "clientName": "openshift-web-console",
      "userName": "ldap:bob",
      "userUID": "123df313-b404-4efe-9856-fdfb13a2a005"
      "scopes": [
          "session"
      ]
  }
  ----
  
  == OAuthAuthorizeToken
  This API is still in development and subject to change.
  
  An OAuthAuthorizeToken represents an OAuth authorization code, as described in
  https://tools.ietf.org/html/rfc6749#section-1.3.1[RFC 6749, section 1.3.1].
  
  
negative.code: ----
  {
      "kind": "OAuthAuthorizeToken",
      "apiVersion": "v1",
      "metadata": {
          "name": "MDAwYjM5YjMtMzM1MC00NDY4LTkxODItOTA2OTE2YzE0M2Fj", <1>
          "resourceVersion": "1",
          "creationTimestamp": "2015-01-01T01:01:01-00:00"
      },
      "clientName": "openshift-web-console", <2>
      "expiresIn": 300, <3>
      "scopes": [],
      "redirectURI": "https://localhost:8443/console/oauth", <4>
      "userName": "bob", <5>
      "userUID": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe" <6>
  }
  ----
  <1> Token name, used as an authorization code to exchange for an OAuthAccessToken
  <2> OAuthClient that requested this token
  <3> Expiration in seconds from the creationTimestamp
  <4> The redirectURI where the user was redirected during the authorization flow that resulted in this token
  <5> The name of the User this token allows obtaining an OAuthAccessToken for.
  <6> The UID of the User this token allows obtaining an OAuthAccessToken for.
  
  === OAuthAccessToken
  An OAuthAccessToken represents an OAuth access token, as described in
  https://tools.ietf.org/html/rfc6749#section-1.4[RFC 6749, section 1.4].
  
  