RNAA Docusaurus v1 site (#981)

Co-authored-by: Charlie Brown <carbonrobot@gmail.com>

Author: wsparsons

.eslintignore

@@ -1 +1,2 @@
-Example
+Example
+docs/docusaurus.config.ts

README.md

@@ -1,5 +1,5 @@
 <a href="https://formidable.com/open-source/" target="_blank">
-  <img alt="React Native App Auth — Formidable, We build the modern web" src="https://raw.githubusercontent.com/FormidableLabs/react-native-app-auth/main/react-native-app-auth-Hero.png" />
+  <img alt="React Native App Auth — Formidable, We build the modern web" src="https://oss.nearform.com/api/banner?text=react+native+app+auth" />
 </a>
 <p align="center">
 <strong>React native bridge for AppAuth - an SDK for communicating with OAuth2 providers</strong>
@@ -124,7 +124,7 @@ with optional overrides.
   - **registrationEndpoint** - (`string`) fully formed url to your OAuth/OpenID Connect registration endpoint. Only necessary for servers that require client registration.
   - **endSessionEndpoint** - (`string`) fully formed url to your OpenID Connect end session endpoint. If you want to be able to end a user's session and no `issuer` is specified, this field is mandatory.
 - **clientId** - (`string`) _REQUIRED_ your client id on the auth server
-- **clientSecret** - (`string`) client secret to pass to token exchange requests. :warning: Read more about [client secrets](#note-about-client-secrets)
+- **clientSecret** - (`string`) client secret to pass to token exchange requests. :warning: Read more about [client secrets](/docs/client-secrets)
 - **redirectUrl** - (`string`) _REQUIRED_ the url that links back to your app with the auth code
 - **scopes** - (`array<string>`) the scopes for your token, e.g. `['email', 'offline_access']`.
 - **additionalParameters** - (`object`) additional parameters that will be passed in the authorization request.
@@ -548,6 +548,6 @@ Please see our [contributing guide](./.github/CONTRIBUTING.md).
 
 ## Maintenance Status
 
-**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.
+**Active:** Nearform is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.
 
 [maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,29 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+This site is deployed using Vercel, which will automatically detect the site config and deploy

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/client-secrets.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+# Client Secrets
+
+Some authentication providers, including examples cited below, require you to provide a client secret. The authors of the AppAuth library
+
+> [strongly recommend](https://github.com/openid/AppAuth-Android#utilizing-client-secrets-dangerous) you avoid using static client secrets in your native applications whenever possible. Client secrets derived via a dynamic client registration are safe to use, but static client secrets can be easily extracted from your apps and allow others to impersonate your app and steal user data. If client secrets must be used by the OAuth2 provider you are integrating with, we strongly recommend performing the code exchange step on your backend, where the client secret can be kept hidden.
+
+Having said this, in some cases using client secrets is unavoidable. In these cases, a `clientSecret` parameter can be provided to `authorize`/`refresh` calls when performing a token request.

docs/docs/config-examples/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Config Examples",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/config-examples/asgardeo.md renamed to docs/docs/config-examples/asgardeo.md

@@ -1,3 +1,5 @@
+# Asgardeo
+
 To add authentication to your app using Asgardeo, you will first need to [create an application](https://wso2.com/asgardeo/docs/guides/applications/register-mobile-app/) in the Asgardeo console. If you don't have an Asgardeo account, [you can signup for one free](https://asgardeo.io/signup).
 
 After creating an application, take note of the configuration values listed in the **Quick Start** and **Info** tabs. You will be using those values as follows.
@@ -7,7 +9,7 @@ export const config = {
   issuer: 'https://api.asgardeo.io/t/<your_org_name>/oauth2/token',
   clientId: '<your_application_id>',
   redirectUrl: '<your_appAuthRedirectScheme>://example',
-  scopes: ['openid', 'profile']
+  scopes: ['openid', 'profile'],
 };
 
 // Log in to get an authentication token
@@ -20,12 +22,12 @@ const refreshedState = await refresh(config, {
 
 // Revoke token
 await revoke(config, {
-  tokenToRevoke: refreshedState.refreshToken
+  tokenToRevoke: refreshedState.refreshToken,
 });
 
 // End session
 await logout(config, {
   idToken: authState.idToken,
-  postLogoutRedirectUrl: '<your_appAuthRedirectScheme>:/logout'
+  postLogoutRedirectUrl: '<your_appAuthRedirectScheme>:/logout',
 });
 ```

docs/config-examples/aws-cognito.md renamed to docs/docs/config-examples/aws-cognito.md

@@ -18,8 +18,8 @@ const config = {
   serviceConfiguration: {
     authorizationEndpoint: '<YOUR_DOMAIN_NAME>/oauth2/authorize',
     tokenEndpoint: '<YOUR_DOMAIN_NAME>/oauth2/token',
-    revocationEndpoint: '<YOUR_DOMAIN_NAME>/oauth2/revoke'
-  }
+    revocationEndpoint: '<YOUR_DOMAIN_NAME>/oauth2/revoke',
+  },
 };
 
 // Log in to get an authentication token
@@ -32,6 +32,6 @@ const refreshedState = await refresh(config, {
 
 // Revoke token
 await revoke(config, {
-  tokenToRevoke: refreshedState.refreshToken
+  tokenToRevoke: refreshedState.refreshToken,
 });
 ```

docs/config-examples/azure-active-directory-b2c.md renamed to docs/docs/config-examples/azure-active-directory-b2c.md

@@ -1,4 +1,4 @@
-## Azure Active Directory B2C
+# Azure Active Directory B2C
 
 Detailed documentation [here](https://docs.microsoft.com/en-us/azure/active-directory-b2c/openid-connect).
 
@@ -7,7 +7,7 @@ const config = {
   issuer: 'https://<TENANT_NAME>.b2clogin.com/<TENANT_NAME>.onmicrosoft.com/<USER_FLOW_NAME>/v2.0',
   clientId: '<APPLICATION_ID>',
   redirectUrl: 'com.myapp://redirect/url/', // the redirectUrl must end with a slash
-  scopes: ['openid', 'offline_access']
+  scopes: ['openid', 'offline_access'],
 };
 
 // Log in to get an authentication token

docs/config-examples/azure-active-directory.md renamed to docs/docs/config-examples/azure-active-directory.md

@@ -12,17 +12,17 @@ See the [Azure docs on requesting an access token](https://docs.microsoft.com/en
 
 Please Note:
 
-* `Scopes` is ignored.
-* `additionalParameters.resource` may be required based on the tenant settings.
+- `Scopes` is ignored.
+- `additionalParameters.resource` may be required based on the tenant settings.
 
 ```js
 const config = {
   issuer: 'https://login.microsoftonline.com/your-tenant-id',
   clientId: 'your-client-id',
   redirectUrl: 'com.myapp://oauth/redirect/',
   additionalParameters: {
-    resource: 'your-resource'
-  }
+    resource: 'your-resource',
+  },
 };
 
 // Log in to get an authentication token
@@ -43,7 +43,7 @@ const config = {
   issuer: 'https://login.microsoftonline.com/your-tenant-id/v2.0',
   clientId: 'your-client-id',
   redirectUrl: 'com.myapp://oauth/redirect/',
-  scopes: ['openid', 'profile', 'email', 'offline_access']
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
 };
 
 // Log in to get an authentication token

docs/config-examples/coinbase.md renamed to docs/docs/config-examples/coinbase.md

@@ -27,6 +27,6 @@ const refreshedState = await refresh(config, {
 
 // Revoke token
 await revoke(config, {
-  tokenToRevoke: refreshedState.refreshToken
+  tokenToRevoke: refreshedState.refreshToken,
 });
 ```

docs/config-examples/dropbox.md renamed to docs/docs/config-examples/dropbox.md

@@ -4,9 +4,9 @@ Dropbox provides an OAuth 2.0 endpoint for logging in with a Dropbox user's cred
 
 Please note:
 
-* Dropbox does not provide a OIDC discovery endpoint, so `serviceConfiguration` is used instead.
-* Dropbox OAuth requires a [client secret](#note-about-client-secrets).
-* Dropbox access tokens are short lived and will expire after a short period of time. To update your access token a separate call needs to be made to [/oauth2/token](https://www.dropbox.com/developers/documentation/http/documentation#oauth2-token) to obtain a new access token.
+- Dropbox does not provide a OIDC discovery endpoint, so `serviceConfiguration` is used instead.
+- Dropbox OAuth requires a [client secret](/docs/client-secrets).
+- Dropbox access tokens are short lived and will expire after a short period of time. To update your access token a separate call needs to be made to [/oauth2/token](https://www.dropbox.com/developers/documentation/http/documentation#oauth2-token) to obtain a new access token.
 
 ```js
 const config = {

docs/config-examples/fitbit.md renamed to docs/docs/config-examples/fitbit.md

@@ -4,8 +4,8 @@ Fitbit provides an OAuth 2.0 endpoint for logging in with a Fitbit user's creden
 
 Please note:
 
-* Fitbit does not provide a OIDC discovery endpoint, so `serviceConfiguration` is used instead.
-* Fitbit OAuth requires a [client secret](#note-about-client-secrets).
+- Fitbit does not provide a OIDC discovery endpoint, so `serviceConfiguration` is used instead.
+- Fitbit OAuth requires a [client secret](/docs/client-secrets).
 
 ```js
 const config = {
@@ -16,8 +16,8 @@ const config = {
   serviceConfiguration: {
     authorizationEndpoint: 'https://www.fitbit.com/oauth2/authorize',
     tokenEndpoint: 'https://api.fitbit.com/oauth2/token',
-    revocationEndpoint: 'https://api.fitbit.com/oauth2/revoke'
-  }
+    revocationEndpoint: 'https://api.fitbit.com/oauth2/revoke',
+  },
 };
 
 // Log in to get an authentication token
@@ -31,6 +31,6 @@ const refreshedState = await refresh(config, {
 // Revoke token
 await revoke(config, {
   tokenToRevoke: refreshedState.refreshToken,
-  includeBasicAuth: true
+  includeBasicAuth: true,
 });
 ```

docs/config-examples/fusionauth.md renamed to docs/docs/config-examples/fusionauth.md

@@ -2,9 +2,9 @@
 
 FusionAuth does not specify a revocation endpoint so revoke functionality doesn't work. Other than that, full functionality is available.
 
-* [Install FusionAuth](https://fusionauth.io/docs/v1/tech/installation-guide).
-* Create an application in the admin screen. Note the client id.
-* Set the redirect_uri for the application to be a value like `fusionauth.demo:/oauthredirect` where `fusionauth.demo` is a scheme you've registered in your application.
+- [Install FusionAuth](https://fusionauth.io/docs/v1/tech/installation-guide).
+- Create an application in the admin screen. Note the client id.
+- Set the redirect_uri for the application to be a value like `fusionauth.demo:/oauthredirect` where `fusionauth.demo` is a scheme you've registered in your application.
 
 Use the following configuration (replacing the `clientId` with your application id and `fusionAuth.demo` with your scheme):
 

docs/config-examples/github.md renamed to docs/docs/config-examples/github.md

@@ -10,13 +10,12 @@ const config = {
   clientId: '<client-id>',
   clientSecret: '<client-secret>',
   scopes: ['identity'],
-  additionalHeaders: { 'Accept': 'application/json' },
+  additionalHeaders: { Accept: 'application/json' },
   serviceConfiguration: {
     authorizationEndpoint: 'https://github.com/login/oauth/authorize',
     tokenEndpoint: 'https://github.com/login/oauth/access_token',
-    revocationEndpoint:
-      'https://github.com/settings/connections/applications/<client-id>'
-  }
+    revocationEndpoint: 'https://github.com/settings/connections/applications/<client-id>',
+  },
 };
 
 // Log in to get an authentication token

docs/config-examples/google.md renamed to docs/docs/config-examples/google.md

@@ -3,31 +3,32 @@
 Full support out of the box.
 
 ```js
-const GOOGLE_OAUTH_APP_GUID = 'YOUR_GOOGLE_OAUTH_APP_GUID' // it looks something like 12345678912-k50abcdefghijkabcdefghijkabcdefv
+const GOOGLE_OAUTH_APP_GUID = 'YOUR_GOOGLE_OAUTH_APP_GUID'; // it looks something like 12345678912-k50abcdefghijkabcdefghijkabcdefv
 const config = {
   issuer: 'https://accounts.google.com',
   clientId: `${GOOGLE_OAUTH_APP_GUID}.apps.googleusercontent.com`,
   redirectUrl: `com.googleusercontent.apps.${GOOGLE_OAUTH_APP_GUID}:/oauth2redirect/google`,
-  scopes: ['openid', 'profile']
+  scopes: ['openid', 'profile'],
 };
 
 // Log in to get an authentication token
 const authState = await authorize(config);
 
 // Refresh token
 const refreshedState = await refresh(config, {
-  refreshToken: authState.refreshToken
+  refreshToken: authState.refreshToken,
 });
 
 // Revoke token
 await revoke(config, {
-  tokenToRevoke: refreshedState.refreshToken
+  tokenToRevoke: refreshedState.refreshToken,
 });
 ```
 
-
 ### Note for Android
+
 To [capture the authorization redirect](https://github.com/openid/AppAuth-android#capturing-the-authorization-redirect), add the following property to the defaultConfig in `android/app/build.gradle`:
+
 ```
 android {
   defaultConfig {
@@ -38,5 +39,6 @@ android {
   }
 }
 ```
+
 - You need to check custom URI scheme under APIs & Services -> Credentials -> OAuth 2.0 Client IDs -> Your Client Name -> Advanced Settings
 - It may take 5 minutes to a few hours for settings to take effect.

docs/config-examples/identity-server-3.md renamed to docs/docs/config-examples/identity-server-3.md

@@ -10,7 +10,7 @@ const config = {
   clientId: 'your-client-id',
   clientSecret: 'your-client-secret',
   redirectUrl: 'com.your.app.name:/oauthredirect',
-  scopes: ['openid', 'profile', 'offline_access']
+  scopes: ['openid', 'profile', 'offline_access'],
 };
 
 // Log in to get an authentication token
@@ -24,7 +24,7 @@ const refreshedState = await refresh(config, {
 // Revoke token, note that Identity Server expects a client id on revoke
 await revoke(config, {
   tokenToRevoke: refreshedState.refreshToken,
-  sendClientId: true
+  sendClientId: true,
 });
 ```
 

docs/config-examples/identity-server-4.md renamed to docs/docs/config-examples/identity-server-4.md

@@ -12,7 +12,7 @@ const config = {
   issuer: 'https://demo.identityserver.io',
   clientId: 'native.code',
   redirectUrl: 'io.identityserver.demo:/oauthredirect',
-  scopes: ['openid', 'profile', 'offline_access']
+  scopes: ['openid', 'profile', 'offline_access'],
 };
 
 // Log in to get an authentication token
@@ -26,7 +26,7 @@ const refreshedState = await refresh(config, {
 // Revoke token, note that Identity Server expects a client id on revoke
 await revoke(config, {
   tokenToRevoke: refreshedState.refreshToken,
-  sendClientId: true
+  sendClientId: true,
 });
 ```
 

docs/config-examples/keycloak.md renamed to docs/docs/config-examples/keycloak.md

@@ -9,7 +9,7 @@ const config = {
   issuer: 'http://localhost:9080/auth/realms/jhipster',
   clientId: 'web_app',
   redirectUrl: '<YOUR_REDIRECT_SCHEME>:/callback',
-  scopes: ['openid', 'profile']
+  scopes: ['openid', 'profile'],
 };
 
 // Log in to get an authentication token

docs/config-examples/microsoft.md renamed to docs/docs/config-examples/microsoft.md

@@ -1,10 +1,11 @@
-## Microsoft
+# Microsoft
 
 1. Supplying "issuer" fails, because Microsoft returns `issuer` with the literal string `https://login.microsoftonline.com/{tenantid}/v2.0` when `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration` is queried.. We need to manually specify `serviceConfiguration`.
 
 2. `REDIRECT_URL` varies based on platform:
+
    - iOS: msauth.com.example.app://auth/
-   - Android: com.example.app://msauth/<SIGNATURE_HASH>/
+   - Android: com.example.app://msauth/`<SIGNATURE_HASH>`/
 
 3. Microsoft does not have. revocationEndpoint.