.. _UC12:

Use Case 12 - User Authentication
---------------------------------

.. index:: Use Case 12, authentication

Goal 
~~~~

User Authentication - A user or a service operating on behalf of a user
authenticates against an identify provider to establish a certificate that can
subsequently be used to identify the user.


Summary
~~~~~~~

Many operations in the DataONE system require affirmation of user identity to
ensure that appropriate access controls can be asserted and other services such
as citation and notification operate as expected.

The actual identity and authentication framework may exist outside of DataONE,
and the first version of the infrastructure will be utilizing the certificate
based services of the `CILogon service`_.

The user obtains a certificate from the CILogon service, then uses that
certificate to make API calls against DataONE Services.

Alternatively, a long lived certificate may be provided by DataONE for systems such as Member Nodes that need to authenticate with components of DataONE.

In each case, the provided certificate contains the subject, alternate subjects, and group memberships of the user. This information is used by services to determine if the caller has access to the requested resource. 

Actors
~~~~~~

User, Member Node, Coordinating Node, Authentication System

Preconditions 
~~~~~~~~~~~~~

- User is not authenticated in the system

Triggers
~~~~~~~~

- A user logs on to the DataONE system.

- A user needs to access a restricted operation.

Post Conditions
~~~~~~~~~~~~~~~

- A certificate is returned to the user that can be used by DataONE services 
  to identify the user.

- In the event of authentication failure the certificate will not be available.

.. uml::

  @startuml images/12_seq_a.png
  actor User
  participant CILogon
  participant IDP <<Identity Provider >>
  participant CN <<Coordinating Node>>

  note right of CILogon
    DataONE Authentication Service
    https://cilogon.org/?skin=dataone
  end note
  User -> CILogon: Authenticate
  activate CILogon
  CILogon -> User: auth_using_IDP

  note right of IDP
    User selected 
    Identity Provider
  end note
  User -> IDP: authenticate
  activate IDP
  IDP -> CILogon: user metadata
  deactivate IDP
  CILogon -> CN: getSubjectInfo
  activate CN
  CN -> CILogon: SubjectInfo
  deactivate CN
  CILogon -> CILogon: generate certificate
  CILogon -> User: certificate_download_tool
  User -> CILogon: download certificate
  CILogon -> User: certificate
  deactivate CILogon

  @enduml

**Figure 1.** Obtaining a client side certificate from the CILogon service.


.. uml::

  @startuml images/12_seq_b.png
  actor User
  participant CA <<Certificate Authority>>
  participant CertProvider 

  note right of CA
    DataONE Certificate Authority. Requires
    manual interaction with DataONE 
    administrators to generate certificate.
  end note
  User -> CA: Request certificate
  activate CA
  CA -> CA: Generate certificate
  CA -> User: Certificate retrieval information
  deactivate CA
  User -> CertProvider: download Certificate
  activate CertProvider
  CertProvider -> User: Certificate
  deactivate CertProvider

  @enduml

**Figure 2.** Obtaining a long-lived client side certificate from DataONE.

.. uml::

  @startuml images/12_seq_c.png
  actor User
  participant MN <<Member Node>>
  note right of MN
    Member Node is shown, however
    process is the same for both 
    Member and Coordianting Nodes
  end note
  User -> MN: restricted operation
  activate MN
  MN -> MN: verify credentials
  MN -> User: response
  deactivate MN
  @enduml


**Figure 3.** Authenticated interaction with service provided by a Member or 
Coordinating Node.


.. _CILogon service: http://www.cilogon.org/service