OAuth2 Client Registration
==========================

Clients (applications which wish to connect to sheepAuth to authenticate users) need to register their applications and collect digital keys.

.. note::

	sheepCRM admin user account required. (If you don't have an admin account please contact us and we will configure on your behalf)


1. Navigate to https://auth.sheepcrm.com/o/applications/

2. Register the Client

	a) Client Name is human readable name that will be used to show a message like “{Client Name}” wants to access your information
	b) Client Type - choose `confidential`
	c) Authorization grant type - choose `Authorization code`
	d) Redirect URIs: (please provide just one) this is the callback that will retrieve an access token; it must be a valid URL and include https:// (Your website plugin or system will tell you the value to use.)
	e) Flock: the sheepCRM database identifier.
	f) Logo: A secure url (https) link to a square logo. This will be used as part of the login process
	g) Security Policy: A secure url (https) link to the security policy for your application.
	h) Terms and Conditions: A secure url (https) link to the terms and conditions for your application.
	i) Your contact details. These details will not be made public but will be used by SheepCRM to communicate with you about your integration.

3. A client ID and secret are returned keep these safe.

4. Use the client ID and secret to configure the OAuth client
	- authorization `https://auth.sheepcrm.com/o/authorize/`
	- token: `https://auth.sheepcrm.com/o/token`
	- user infomation: `https://iam.sheepcrm.com/userinfo/`
	- token url method: `POST`

Available Scopes to request
^^^^^^^^^^^^^^^^^^^^^^^^^^^

:read:
	view your profile information
:write:
	update your profile
:read_membership:
	view your membership information
:introspection:
	Introspect token scope

authorization optional parameters
- `flock` {your sheep database identifier}
- `approval_prompt`
	- `force` - users are always prompted for authorization.
	- `auto` - users are prompted only the first time, subsequent authorizations for the same application and scopes will be automatically accepted.

.. note::

	Digital Ocean provide a great tutorial that explains how OAuth works.
	https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2