diff --git a/README.md b/README.md index b10d496e..40b4f9b1 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ to do: used to connect to the KBase Auth Server, which provides a context for authenticating and authorizing DTS for its basic operations * `DTS_KBASE_TEST_ORCID`: an [ORCID](https://orcid.org/) identifier that can be - used to run DTS's unit test. This identifier must match a registered ORCID ID + used to run DTS's unit test. This identifier must match a registered ORCID associated with a [KBase user account](https://narrative.kbase.us/#signup). * `DTS_KBASE_TEST_USER`: the KBase user associated with the ORCID specified by `DTS_KBASE_TEST_ORCID`. diff --git a/auth/kbase_auth_server.go b/auth/kbase_auth_server.go index 54d84691..9d184a9c 100644 --- a/auth/kbase_auth_server.go +++ b/auth/kbase_auth_server.go @@ -226,7 +226,7 @@ func (server KBaseAuthServer) kbaseUser() (kbaseUser, error) { } } if !foundOrcid { - return user, fmt.Errorf("KBase Auth2: No ORCID IDs associated with this user!") + return user, fmt.Errorf("KBase Auth2: No ORCIDs associated with this user!") } return user, err } diff --git a/auth/kbase_user_federation.go b/auth/kbase_user_federation.go index f2f53b6d..c8b6e7d0 100644 --- a/auth/kbase_user_federation.go +++ b/auth/kbase_user_federation.go @@ -34,7 +34,7 @@ import ( // users who have made requests to the DTS. This prevents us from having to // rely on a secondary data source for this information. -// associates the given KBase username with the given ORCID ID +// associates the given KBase username with the given ORCID func SetKBaseLocalUsernameForOrcid(orcid, username string) error { if !kbaseUserFederationStarted { // fire it up! @@ -49,7 +49,7 @@ func SetKBaseLocalUsernameForOrcid(orcid, username string) error { return err } -// returns the local KBase username associated with the given ORCID ID +// returns the local KBase username associated with the given ORCID func KBaseLocalUsernameForOrcid(orcid string) (string, error) { if !kbaseUserFederationStarted { // no one's logged in! return "", fmt.Errorf("KBase federated user table not available!") @@ -70,8 +70,8 @@ var kbaseOrcidUserChan chan [2]string // passes (ORCIDs, username) pairs in var kbaseUserChan chan string // passes usernames out var kbaseErrorChan chan error // passes errors out -// This goroutine maintains a mapping or ORCID IDS to local KBase users, -// fielding requests to update and retrieve usernames by ORCID ID. +// This goroutine maintains a mapping or ORCIDs to local KBase users, +// fielding requests to update and retrieve usernames by ORCID. func kbaseUserFederation(started chan struct{}) { // channels kbaseOrcidChan = make(chan string) @@ -79,7 +79,7 @@ func kbaseUserFederation(started chan struct{}) { kbaseUserChan = make(chan string) kbaseErrorChan = make(chan error) - // mapping of ORCID IDs to local KBase users + // mapping of ORCIDs to local KBase users kbaseUserTable := make(map[string]string) // we're ready diff --git a/databases/databases.go b/databases/databases.go index 3e78aa27..193cb52a 100644 --- a/databases/databases.go +++ b/databases/databases.go @@ -131,7 +131,7 @@ func RegisterDatabase(dbName string, createDb func(orcid string) (Database, erro } } -// creates a database proxy associated with the given ORCID ID, based on the +// creates a database proxy associated with the given ORCID, based on the // configured type, or returns an existing instance func NewDatabase(orcid, dbName string) (Database, error) { var err error diff --git a/databases/jdp/database.go b/databases/jdp/database.go index b5306d14..ef706cab 100644 --- a/databases/jdp/database.go +++ b/databases/jdp/database.go @@ -72,7 +72,7 @@ type StagingRequest struct { func NewDatabase(orcid string) (databases.Database, error) { if orcid == "" { - return nil, fmt.Errorf("No ORCID ID was given") + return nil, fmt.Errorf("No ORCID was given") } // make sure we have a shared secret or an SSO token diff --git a/databases/kbase/database.go b/databases/kbase/database.go index 1924d510..32beb622 100644 --- a/databases/kbase/database.go +++ b/databases/kbase/database.go @@ -40,7 +40,7 @@ type Database struct { func NewDatabase(orcid string) (databases.Database, error) { if orcid == "" { - return nil, fmt.Errorf("No ORCID ID was given") + return nil, fmt.Errorf("No ORCID was given") } return &Database{ diff --git a/databases/nmdc/database.go b/databases/nmdc/database.go index 5cd6629a..077f15f5 100644 --- a/databases/nmdc/database.go +++ b/databases/nmdc/database.go @@ -63,7 +63,7 @@ func NewDatabase(orcid string) (databases.Database, error) { if orcid == "" { return nil, databases.UnauthorizedError{ Database: "nmdc", - Message: "No ORCID ID was given", + Message: "No ORCID was given", } } diff --git a/docs/admin/installation.md b/docs/admin/installation.md index 29eaf9ad..9bc94180 100644 --- a/docs/admin/installation.md +++ b/docs/admin/installation.md @@ -35,13 +35,13 @@ needs to do: authenticating and authorizing the DTS for its basic operations. You can create a token [from your KBase developer account](https://kbase.github.io/kb_sdk_docs/tutorial/3_initialize.html#set-up-your-developer-credentials). * `DTS_KBASE_TEST_ORCID`: an [ORCID](https://orcid.org/) identifier that can be - used to run the DTS's unit test. This identifier must match a registered ORCID ID + used to run the DTS's unit test. This identifier must match a registered ORCID associated with a [KBase user account](https://narrative.kbase.us/#signup). * `DTS_KBASE_TEST_USER`: the KBase user associated with the ORCID specified by `DTS_KBASE_TEST_ORCID`. **NOTE: at the time of writing, KBase does not have - a mechanism for mapping ORCID IDs to local users, so the DTS uses a file in - its data directory called `kbase_users.json` consisting of a single JSON - object whose keys are ORCID IDs and whose values are local usernames.** + a mechanism for mapping ORCIDs to local users, so the DTS uses a file in its + data directory called `kbase_users.json` consisting of a single JSON object + whose keys are ORCIDs and whose values are local usernames.** * `DTS_GLOBUS_CLIENT_ID`: a client ID registered using the [Globus Developers](https://docs.globus.org/globus-connect-server/v5/use-client-credentials/#register-application) web interface. This ID must be registered specifically for an instance of diff --git a/docs/integration/glossary.md b/docs/integration/glossary.md index 453b3148..c6a04a83 100644 --- a/docs/integration/glossary.md +++ b/docs/integration/glossary.md @@ -43,9 +43,9 @@ We use the following terms in the DTS Integration Guide. level of the directory structure transferred to the destination database. a source database to a destination database by the DTS * **User federation endpoint**: An endpoint provided by your database that - accepts an HTTP `GET` request with an ORCID ID and produces a response + accepts an HTTP `GET` request with an ORCID and produces a response containing the corresponding username for an account within your system. - Read more about this endpoint in [Map ORCID IDs to Local User Accounts](local_user.md). + Read more about this endpoint in [Map ORCIDs to Local User Accounts](local_user.md). * **UUID**: A [universally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) used by the DTS to represent staging tasks, transfers, and other transient- but-possibly-long-running operations diff --git a/docs/integration/index.md b/docs/integration/index.md index 9173f011..6ef7f2ef 100644 --- a/docs/integration/index.md +++ b/docs/integration/index.md @@ -77,15 +77,14 @@ The sections that follow describe each of these items in more detail. Additionally, your database must provide a **staging status endpoint** that accepts an HTTP request with a staging request UUID and produces a response that indicates whether the staging process has completed. -6. **Your database can map ORCID IDs to local users within your organization.** - Every DTS user must authenticate with an ORCID ID to connect to the service. - To establish a connection between the ORCID ID and a specific user account +6. **Your database can map ORCIDs to local users within your organization.** + Every DTS user must authenticate with an ORCID to connect to the service. + To establish a connection between the ORCID and a specific user account for your organization, your database must provide a **user federation - endpoint** that accepts an HTTP request with an ORCID ID and produces - a response containing the corresponding username for an account within your - system. This federation process allows DTS to associate a transfer operation - with user accounts in the organizations for the source and destination - databases. + endpoint** that accepts an HTTP request with an ORCID and produces a response + containing the corresponding username for an account within your system. This + federation process allows DTS to associate a transfer operation with user + accounts in the organizations for the source and destination databases. If your organization has existing services that provide similar capabilities but use different conventions, or if you have other technical considerations, please @@ -99,4 +98,4 @@ best of what you have. * [Provide a Staging Area for Your Files](staging_area.md) * [Stage Your Files on Request](stage_files.md) * [Provide a Way to Monitor File Staging](staging_status.md) -* [Map ORCID IDs to Local User Accounts](local_user.md) +* [Map ORCIDs to Local User Accounts](local_user.md) diff --git a/docs/integration/local_user.md b/docs/integration/local_user.md index 0288213d..498dd230 100644 --- a/docs/integration/local_user.md +++ b/docs/integration/local_user.md @@ -1,27 +1,27 @@ -# Map ORCID IDs to Local User Accounts +# Map ORCIDs to Local User Accounts -The Data Transfer System (DTS) uses [ORCID IDs](https://info.orcid.org/what-is-orcid/) +The Data Transfer System (DTS) uses [ORCIDs](https://info.orcid.org/what-is-orcid/) to identify individuals and organizations. In order to understand who is transferring what where when, your database must establish a connection between -a user's ORCID ID and their local account on your system. This connection is a +a user's ORCID and their local account on your system. This connection is a form of [federated identity management](https://en.wikipedia.org/wiki/Federated_identity), similar to Single Sign-On (SSO) authentication services offered by various platforms. ## Endpoint Recommendations -Create a REST endpoint that accepts an HTTP `GET` request with a given ORCID ID +Create a REST endpoint that accepts an HTTP `GET` request with a given ORCID as a path parameter or request parameter. This endpoint responds with a body containing a JSON object with two fields: -* `orcid`: the ORCID ID passed as the query parameter -* `username`: the local username corresponding to the given ORCID ID +* `orcid`: the ORCID passed as the query parameter +* `username`: the local username corresponding to the given ORCID Error codes should be used in accordance with HTTP conventions: * A successful query returns a `200 OK` status code -* An improperly-formed ORCID ID should result in a `400 Bad Request` status code -* An ORCID ID that does not correspond to a local user should produce `404 Not Found` +* An improperly-formed ORCID should result in a `400 Bad Request` status code +* An ORCID that does not correspond to a local user should produce `404 Not Found` ### Example @@ -48,7 +48,7 @@ This produces a responѕe with a `200 OK` status code with the body This particular feature is actually not yet supported by KBase, so the DTS prototype uses a locally-stored JSON file containing an object whose -field names are ORCID IDs and whose values are usernames for the corresponding +field names are ORCIDs and whose values are usernames for the corresponding KBase users. * Example: current workaround (to be updated when JDP and KBase support this!) diff --git a/mkdocs.yml b/mkdocs.yml index 76551e32..6a54e08d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,7 @@ nav: - 'Provide a Staging Area for Your Files': 'integration/staging_area.md' - 'Stage Your Files on Request': 'integration/stage_files.md' - 'Provide a Way to Monitor File Staging': 'integration/staging_status.md' - - 'Map ORCID IDs to Local User Accounts': 'integration/local_user.md' + - 'Map ORCIDs to Local User Accounts': 'integration/local_user.md' - 'Glossary': 'integration/glossary.md' - 'Developer Guide': - 'Overview': 'developer/index.md'