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


.. note::
	For **Wordpress** we highly recommend the `miniOrange WordPress OAuth Client plugin <https://plugins.miniorange.com/wordpress-sso>`_
	see their `Setup Guide <https://plugins.miniorange.com/sheepcrm-oauth-and-openid-connect-single-sign-on-sso-login>`_ and `Video Tutorial <https://www.youtube.com/watch?v=Qc1pS-B5ASI>`_

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

:Client Name:
	is human readable name that will be used to show a message like “{Client Name}” wants to access your information
:Client Type:
	choose `confidential`
:Authorization grant type:
	choose `Authorization code`
: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.)
:Flock:
	the sheepCRM database identifier (required unless the client for multiple Sheep databases).
:Logo:
	A secure url (https) link to a square logo. This will be used as part of the login process
:Security Policy:
	A secure url (https) link to the security policy for your application.
:Terms and Conditions:
	A secure url (https) link to the terms and conditions for your application.
: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`

.. note::

	Note the trailing slash on the urls.


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

:read:
	view your profile information: `first_name`, `last_name`, `photo`,
:write:
	update your profile
:read_membership:
	view your membership information: `active_member`, `membership_type`, `membership_start_date`, `membership_end_date`
:introspection:
	Introspect token scope

authorization optional parameters:

:flock:
	your sheep database identifier (this is required if the client is for multiple Sheep databases)
: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