From dd061baaf53f52eebf38895fb67e5d0e0bbc7859 Mon Sep 17 00:00:00 2001 From: Matthew Arofin Date: Mon, 10 Oct 2022 14:37:46 -0400 Subject: [PATCH 1/3] Initial commit - rough draft structure --- Auth0_API_docs.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 Auth0_API_docs.md diff --git a/Auth0_API_docs.md b/Auth0_API_docs.md new file mode 100644 index 0000000..947f1c2 --- /dev/null +++ b/Auth0_API_docs.md @@ -0,0 +1,63 @@ +#Auth0's API Documentation + +##**Contents** +• [Overview][] + +• [Strengths/Why Auth0][] +• [Process Flow - Proof Key for Code Exchange - User experience][] +• [What does it do?][] + + + +##[Overview][] +Auth0's Authentication API allows you to manage all aspects of user identity, offering enpoints that allow users to sign up, log in/out, access other APIs and more. + +All requests must be secure, i.e. `HTTPS`, not `HTTP` + + + + +##[Why the switch?][] +Okta and Auth0 share similar features, such as single sign-on, identity management, and user governance tools. In fact, Auth0 was acquired bybOkta in May 2021, with the former becoming an independent business unit within the latter. While Auth0 may appeal to small to medium sized enterprises with its forever free tier, Okta is attractive to larger organisations with thousands of users and the need for more advanced security protocols. + + +###Auth0: +• Has multi-factor authentication tools +• Does not support biometric authentication or +• Designed with application builders in mind, providing simplicity and strong "identity management protocols" +• Can handle up to 50,000 external users and over 5,000 internal employees[*][5] +[*Free tier supports up to 7,000 active users and unlimited logins*][5] + +###Okta: +• Supports [zero trust networking]() +• Supports biometric authentication +• Offers a more complex and secure system, +• Has no limit regarding the number of active users + +##[What does Auth0 do?][] +###Simplified: +After Auth0 has been implemented in an application, users who try to login will be redirected to a customisable login page where they can input their credentials. If authenticated, Auth0 redirects the user back to your app, returning a JSON Web Token (JWT) with their authentication and user information. + +###Detailed: +1. User clicks Login within application. +2. Auth0's SDL creates a cryptographically random `code_verifier` and from this generates a `code_challenge`. +3. Auth0's SDK redirects the user to the Auth0 Authorization Server [`/authorize` endpoint]() along with the `code_challenge`. +4. Your Auth0 Server redirects user to login and authorization prompt. +5. User authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the application. +6. Your Auth0 Authorization Server stores the `code_challenge` and redicrects the user back to the application with an authorization `code`, which is good for one use. +7. Auth0's SDK sends this `code` and the `code_verifier` (step 2) to the Auth0 Authorization Server ([`/oauth/token` endpoint] ()). +8. Your Auth0 Authorixation Server verifies the `code_challenge` and `code_verifier`. +9. Your Auth0 Authorization Server responds with an ID token and access token +10. Your application can use the access token to call an Api to access information about the user. +11. The API responds with requested data. + + +##[How does Auth0 work?][] +The auth0-react.js library can be used to implement authentication and authorization in React apps with Auth0. It provides a custom React hook and other Higher Order Components to help secure apps in fewer lines of code. There are three ways to authenticate with this API: +*OAuth2 token* +By sending a valid Access Token in the `Authorization` header, you can then make requests to an endpoint (protected routing?) +*Client ID and Client Secret* +By sending your Client ID and Client Secret information in the request JSON body. This option is only available for confidential applications - such as those able to store credentials securely without exposing them to unauthorized parties. +*Client ID* +For public applications that cannot securely hold credentials (SPAs or mobile apps), some endpoints are accessible using only Client ID. \ No newline at end of file From f9c2bc52074673237827a769d5669685d0abdbd1 Mon Sep 17 00:00:00 2001 From: Matthew Arofin Date: Tue, 17 Jan 2023 18:15:03 +0100 Subject: [PATCH 2/3] Update to remove redundant comments, explain Auth0 implementation in , and clean up sections --- .DS_Store | Bin 0 -> 6148 bytes Auth0_API_docs.md | 91 ++++++++++++++++++++++++++-------------------- 2 files changed, 52 insertions(+), 39 deletions(-) create mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..8da67fb1a3076df5eb146f6058803f25125b78b1 GIT binary patch literal 6148 zcmeHK&ubGw6n>LNyRir;D94jo9VK*%9s}BicaMGWWU%{q zpMvtm2;%PVM+nFHzaF8Z>QLld$rM2>no9m9_Y&dVcz8rf+P>k|+Fnq9pe9xp)83iGP-!XYwP{iftA9s*>9VFX0o6UtsHlH_TF*ouV~I zTBpa@n~$hVPsyY15|SH8gjM4ygJnr$TSt7nI#j9XW zbTM~2^aQwKUX}Pg=idNXE7!(=nOn}rwe?^FTLvrx|0)B#Ke$lFmcf}uwRIp-R{&rc z#Y$lF4+8tR23rPa8c_og+7+l>g}Gt~?T&KSv}+lhY1Hl{%;iIvo`t!g2-Q2{yQ(>f zmPVUe1}p=M46NyFmCyg~&+q?>PBv#5unhcH42W{a>$LGn=4`$4aeUUg(6>+)Za34Y lT#%UKSQ&g2Z$p)!&SeAGGC0$S5{Uf~P&C-YGVn(k_yN={vMm4r literal 0 HcmV?d00001 diff --git a/Auth0_API_docs.md b/Auth0_API_docs.md index 947f1c2..280772a 100644 --- a/Auth0_API_docs.md +++ b/Auth0_API_docs.md @@ -1,63 +1,76 @@ -#Auth0's API Documentation +# Auth0's API Documentation -##**Contents** -• [Overview][] - -• [Strengths/Why Auth0][] -• [Process Flow - Proof Key for Code Exchange - User experience][] -• [What does it do?][] +## **Contents** - +• [Overview](#overview) +• [Why Auth0](#justifications) +• [Process Flow - Proof Key for Code Exchange - User experience](#process-flow) +• [What does it do?](#actions) +• [Site Implementation Details](#implementation) -##[Overview][] -Auth0's Authentication API allows you to manage all aspects of user identity, offering enpoints that allow users to sign up, log in/out, access other APIs and more. +## [Overview](#overview) -All requests must be secure, i.e. `HTTPS`, not `HTTP` +The purpose of this document is to clarify some of the essential considerations that informed the migration of the Underdog Devs platform from using Okta to using Auth0 for user authentication on its site. It includes high-level explanations of key concetps and processes, references to relevant internal and external sources of truth on the services mentioned, and an explanation of how and where it has been implemented across Underdog Devs repositories. +Auth0's Authentication API allows you to manage all aspects of user identity, offering endpoints that allow users to sign up, log in/out, access other APIs and more. - +When testing endpoints, ensure requests are sent using `HTTP` -##[Why the switch?][] -Okta and Auth0 share similar features, such as single sign-on, identity management, and user governance tools. In fact, Auth0 was acquired bybOkta in May 2021, with the former becoming an independent business unit within the latter. While Auth0 may appeal to small to medium sized enterprises with its forever free tier, Okta is attractive to larger organisations with thousands of users and the need for more advanced security protocols. +## [Why Auth0?](#justifications) - -###Auth0: -• Has multi-factor authentication tools -• Does not support biometric authentication or -• Designed with application builders in mind, providing simplicity and strong "identity management protocols" -• Can handle up to 50,000 external users and over 5,000 internal employees[*][5] -[*Free tier supports up to 7,000 active users and unlimited logins*][5] +Okta and Auth0 share similar features, such as single sign-on, identity management, and user governance tools. In fact, Auth0 was acquired by Okta in May 2021, with the former becoming an independent business unit within the latter. While Auth0 may appeal to small to medium sized enterprises with its forever free tier, Okta is attractive to larger organisations with thousands of users and the need for more advanced security protocols. Below are a few more contrasts between the services provided by these two platforms: -###Okta: -• Supports [zero trust networking]() -• Supports biometric authentication -• Offers a more complex and secure system, -• Has no limit regarding the number of active users +### Auth0: -##[What does Auth0 do?][] -###Simplified: -After Auth0 has been implemented in an application, users who try to login will be redirected to a customisable login page where they can input their credentials. If authenticated, Auth0 redirects the user back to your app, returning a JSON Web Token (JWT) with their authentication and user information. +- Primarily focused on authentication, providing multi-factor authentication tools and supporting a wide range of identity providers, including social media logins +- Does not support biometric authentication or zero trust networking +- Designed with application builders in mind, providing simplicity and strong "identity management protocols" +- More developer-centric, offering greater flexibility and customisation options +- Can handle up to 50,000 external users and over 5,000 internal employees + [*Free tier supports up to 7,000 active users and unlimited logins*] + +### Okta: + +- Supports [zero trust networking](https://www.cisco.com/c/en/us/solutions/automation/what-is-zero-trust-networking.html) +- Supports biometric authentication +- Offers a more complex and secure system that is geared towards IT professionals +- Primarily supports enterprise identity providers such as Active Directory +- Has no limit regarding the number of active users + +## [What does Auth0 do?](#process-flow) + +### Simplified: + +After Auth0 has been implemented in an application, users who try to login will be redirected to a customisable login page where they can input their credentials. If authenticated, Auth0 redirects the user back to your app, returning a JSON Web Token (JWT) with their authentication and user information. + +### Detailed: -###Detailed: 1. User clicks Login within application. 2. Auth0's SDL creates a cryptographically random `code_verifier` and from this generates a `code_challenge`. -3. Auth0's SDK redirects the user to the Auth0 Authorization Server [`/authorize` endpoint]() along with the `code_challenge`. +3. Auth0's SDK redirects the user to the Auth0 Authorization Server along with the `code_challenge`. 4. Your Auth0 Server redirects user to login and authorization prompt. 5. User authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the application. 6. Your Auth0 Authorization Server stores the `code_challenge` and redicrects the user back to the application with an authorization `code`, which is good for one use. -7. Auth0's SDK sends this `code` and the `code_verifier` (step 2) to the Auth0 Authorization Server ([`/oauth/token` endpoint] ()). -8. Your Auth0 Authorixation Server verifies the `code_challenge` and `code_verifier`. +7. Auth0's SDK sends this `code` and the `code_verifier` (step 2) to the Auth0 Authorization Server. +8. Your Auth0 Authorization Server verifies the `code_challenge` and `code_verifier`. 9. Your Auth0 Authorization Server responds with an ID token and access token 10. Your application can use the access token to call an Api to access information about the user. 11. The API responds with requested data. +## [How does Auth0 work?](#actions) -##[How does Auth0 work?][] The auth0-react.js library can be used to implement authentication and authorization in React apps with Auth0. It provides a custom React hook and other Higher Order Components to help secure apps in fewer lines of code. There are three ways to authenticate with this API: -*OAuth2 token* +_OAuth2 token_ By sending a valid Access Token in the `Authorization` header, you can then make requests to an endpoint (protected routing?) -*Client ID and Client Secret* +_Client ID and Client Secret_ By sending your Client ID and Client Secret information in the request JSON body. This option is only available for confidential applications - such as those able to store credentials securely without exposing them to unauthorized parties. -*Client ID* -For public applications that cannot securely hold credentials (SPAs or mobile apps), some endpoints are accessible using only Client ID. \ No newline at end of file +_Client ID_ +For public applications that cannot securely hold credentials (SPAs or mobile apps), some endpoints are accessible using only Client ID. + +For greater context, check out the [Auth0 Authenticatin API docs website](https://auth0.com/docs/api/authentication#introduction) + +## [Underdog Devs Site Implementation Details](#implementation): + +Auth0 is implemented via the auth0Middleware which lives in the `underdog-devs-be-a/api/middleware/auth0Middleware.js` file in the backend repository. Opening this file, we are particularly interested in the _verifyJWT_ method, which executes an express middleware to verify JSON Web Tokens - this is the method that is called in the _authRequired_ method which is responsible for protected routing. + +When invoked, _verifyJWT_ returns a JWT config object, and also specifies an 'unless' condition which takes an object containing a path parameter which is an array. The paths specified in this array represent public endpoint routes which require no authentication (e.g. `/application/new/:role`, which is the endpoint used to submit new mentor/mentee applications). By specifying exceptions to protected routing in this way, individual endpoints do not need to be targeted to implement or remove authentication. From 1f8a1bfc8e9ba1e929fb7e6c7a979648ee643a17 Mon Sep 17 00:00:00 2001 From: Matthew Arofin Date: Tue, 17 Jan 2023 18:18:31 +0100 Subject: [PATCH 3/3] Added link to auth0 docs authorization flow --- Auth0_API_docs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Auth0_API_docs.md b/Auth0_API_docs.md index 280772a..5c5c83a 100644 --- a/Auth0_API_docs.md +++ b/Auth0_API_docs.md @@ -57,6 +57,8 @@ After Auth0 has been implemented in an application, users who try to login will 10. Your application can use the access token to call an Api to access information about the user. 11. The API responds with requested data. +This process is illustrated in with greater context in the [Authorization code flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). + ## [How does Auth0 work?](#actions) The auth0-react.js library can be used to implement authentication and authorization in React apps with Auth0. It provides a custom React hook and other Higher Order Components to help secure apps in fewer lines of code. There are three ways to authenticate with this API: @@ -67,7 +69,7 @@ By sending your Client ID and Client Secret information in the request JSON body _Client ID_ For public applications that cannot securely hold credentials (SPAs or mobile apps), some endpoints are accessible using only Client ID. -For greater context, check out the [Auth0 Authenticatin API docs website](https://auth0.com/docs/api/authentication#introduction) +For greater context, check out the [Auth0 Authenticatin API docs website](https://auth0.com/docs/api/authentication#introduction). ## [Underdog Devs Site Implementation Details](#implementation):