{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Authentication is a difficult topic fraught with potential pitfalls and complicated configuration options. Panel aims to be a \"batteries-included\" package for building applications and dashboards and therefore ships with a number of inbuilt providers for authentication in an application.\n",
    "\n",
    "The primary mechanism by which Panel performs autentication is [OAuth 2.0](https://oauth.net/2/). The official specification for OAuth 2.0 describes the protocol as follows:\n",
    "\n",
    "    The OAuth 2.0 authorization framework enables a third-party\n",
    "    application to obtain limited access to an HTTP service, either on\n",
    "    behalf of a resource owner by orchestrating an approval interaction\n",
    "    between the resource owner and the HTTP service, or by allowing the\n",
    "    third-party application to obtain access on its own behalf.\n",
    "    \n",
    "In other words OAuth outsources authentication to a third party provider, e.g. GitHub, Google or Azure AD, to authenticate the user credentials and give limited access to the APIs of that service.\n",
    "\n",
    "Note that since Panel is built on Bokeh server and Tornado it is also possible to implement your own authentication independent of the OAuth components shipped with Panel, [see the Bokeh documentation](https://docs.bokeh.org/en/latest/docs/user_guide/server.html#authentication) for further information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring OAuth\n",
    "\n",
    "The OAuth component will stop any user from accessing the application before first logging into the selected provider. The configuration to set up OAuth is all handled via the global `pn.config` object, which has a number of OAuth related parameters. When launching the application via the `panel serve` CLI command these config options can be set as CLI arguments or environment variables, when using the `pn.serve` function on the other hand these variables can be passed in as arguments.\n",
    "\n",
    "### `oauth_provider`\n",
    "\n",
    "The first step in configuring a OAuth is to specify a specific OAuth provider. Panel ships with a number of providers by default:\n",
    "\n",
    "* `azure`: Azure Active Directory\n",
    "* `bitbucket`: Bitbucket\n",
    "* `github`: GitHub\n",
    "* `gitlab`: GitLab\n",
    "* `google`: Google\n",
    "* `okta`: Okta\n",
    "\n",
    "We will go through the process of configuring each of these individually later but for now all we need to know that the `oauth_provider` can be set on the commandline using the `--oauth-provider` CLI argument to `panel serve` or the `PANEL_OAUTH_PROVIDER` environment variable.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-provider=...\n",
    "\n",
    "PANEL_OAUTH_PROVIDER=... panel serve oauth_example.py\n",
    "```\n",
    "\n",
    "### `oauth_key` and `oauth_secret`\n",
    "\n",
    "To authenticate with a OAuth provider we generally require two pieces of information (although some providers will require more customization):\n",
    "\n",
    "1. The Client ID is a public identifier for apps.\n",
    "2. The Client Secret is a secret known only to the application and the authorization server.\n",
    "\n",
    "These can be configured in a number of ways the client ID and client secret can be supplied to the `panel serve` command as `--oauth-key` and `--oauth-secret` CLI arguments or `PANEL_OAUTH_KEY` and `PANEL_OAUTH_SECRET` environment variables respectively.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-key=... --oauth-secret=...\n",
    "\n",
    "PANEL_OAUTH_KEY=... PANEL_OAUTH_KEY=... panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### `oauth_extra_params`\n",
    "\n",
    "Some OAuth providers will require some additional configuration options which will become part of the OAuth URLs. The `oauth_extra_params` configuration variable allows providing this additional information and can be set using the `--oauth-extra-params` CLI argument or `PANEL_OAUTH_EXTRA_PARAMS`.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-extra-params={'tenant_id': ...}\n",
    "\n",
    "PANEL_OAUTH_EXTRA_PARAMS={'tenant_id': ...} panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### `cookie_secret`\n",
    "\n",
    "Once authenticated the user information and authorization token will be set as secure cookies. Cookies are not secure and can easily be modified by clients. A secure cookie ensures that the user information cannot be interfered with or forged by the client by signing it with a secret key. Note that secure cookies guarantee integrity but not confidentiality. That is, the cookie cannot be modified but its contents can be seen by the user. To generate a `cookie_secret` use the `panel secret` CLI argument or generate some other random non-guessable string, ideally with at least 256-bits of entropy.\n",
    "\n",
    "To set the `cookie_secret` supply `--cookie-secret` as a CLI argument or set the `PANEL_COOKIE_SECRET` environment variable.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --cookie-secret=...\n",
    "\n",
    "PANEL_COOKIE_SECRET=... panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### `oauth_expiry`\n",
    "\n",
    "The OAuth expiry configuration value determines for how long an OAuth token will be valid once it has been issued. By default it is valid for 1 day, but may be overwritten by providing the duration in the number of days (decimal values are allowed).\n",
    "\n",
    "To set the `oauth_expiry` supply `--oauth-expiry-days` as a CLI argument or set the `PANEL_OAUTH_EXPIRY` environment variable.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-expiry-days=...\n",
    "\n",
    "PANEL_OAUTH_EXPIRY=... panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### Encryption\n",
    "\n",
    "The architecture of the Bokeh/Panel server means that credentials stored as cookies can be leak in a number of ways. On the initial HTTP(S) request the server will respond with the HTML document that renders the application and this will include an unencrypted token containing the OAuth information. To ensure that the user information and access token are properly encrypted we rely on the Fernet encryption in the `cryptography` library. You can install it with `pip install cryptography` or `conda install cryptography`.\n",
    "\n",
    "Once installed you will be able to generate a encryption key with `panel oauth-secret`. This will generate a secret you can pass to the `panel serve` CLI command using the ``--oauth-encryption-key`` argument or `PANEL_OAUTH_ENCRYPTION` environment variable.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-encryption-key=...\n",
    "\n",
    "PANEL_OAUTH_ENCRYPTION=... panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### Redirect URI\n",
    "\n",
    "Once the OAuth provider has authenticated a user it has to redirect them back to the application, this is what is known as the redirect URI. For security reasons this has to match the URL registered with the OAuth provider exactly. By default Panel will redirect the user straight back to the original URL of your app, e.g. when you're hosting your app at `https://myapp.myprovider.com` Panel will use that as the redirect URI. However in certain scenarios you may override this to provide a specific redirect URI. This can be achieved with the `--oauth-redirect-uri` CLI argument or the `PANEL_OAUTH_REDIRECT_URI` environment variable.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-redirect-uri=...\n",
    "\n",
    "PANEL_OAUTH_REDIRECT_URI=... panel serve oauth_example.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Summary\n",
    "\n",
    "A fully configured OAuth configuration may look like this:\n",
    "\n",
    "```\n",
    "panel serve oauth_example.py --oauth-provider=github --oauth-key=... --oauth-secret=... --cookie-secret=... --oauth-encryption-key=...\n",
    "\n",
    "PANEL_OAUTH_PROVIDER=... PANEL_OAUTH_KEY=... PANEL_OAUTH_SECRET=... PANEL_COOKIE_SECRET=... PANEL_OAUTH_ENCRYPTION=... panel serve oauth_example.py ...`\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing OAuth information\n",
    "\n",
    "Once a user is authorized with the chosen OAuth provider certain user information and an `access_token` will be available to be used in the application to customize the user experience. Like all other global state this may be accessed on the `pn.state` object, specifically it makes three attributes available:\n",
    "\n",
    "* **`pn.state.user`**: A unique name, email or ID that identifies the user.\n",
    "* **`pn.state.access_token`**: The access token issued by the OAuth provider to authorize requests to its APIs.\n",
    "* **`pn.state.user_info`**: Additional user information provided by the OAuth provider. This may include names, email, APIs to request further user information, IDs and more."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## OAuth Providers\n",
    "\n",
    "Panel provides a  number of inbuilt OAuth providers, below is the list\n",
    "\n",
    "### **Azure Active Directory**\n",
    "\n",
    "To set up OAuth2.0 authentication for Azure Active directory follow [these instructions](https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-protect-backend-with-aad). In addition to the `oauth_key` and `oauth_secret` ensure that you also supply the tenant ID using `oauth_extra_params`, e.g.:\n",
    "\n",
    "```\n",
    "panel serve oauth_test.py --oauth-extra-params=\"{'tenant': '...'}\"\n",
    "\n",
    "PANEL_OAUTH_EXTRA_PARAMS=\"{'tenant': '...'}\" panel serve oauth_example.py ...\n",
    "```\n",
    "\n",
    "### **Bitbucket**\n",
    "\n",
    "Bitbucket provides instructions about setting [setting up an OAuth consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). Follow these and then supply the `oauth_key` and `oauth_secret` to Panel as described above.\n",
    "\n",
    "### **GitHub** \n",
    "\n",
    "GitHub provides detailed instructions on [creating an OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). Follow these and then supply the `oauth_key` and `oauth_secret` to Panel as described above.\n",
    "\n",
    "### **GitLab**\n",
    "\n",
    "GitLab provides a detailed guide on [configuring an OAuth](https://docs.gitlab.com/ee/api/oauth2.html) application. In addition to the `oauth_key` and `oauth_secret` you will also have to supply a custom url using the `oauth_extra_params` if you have a custom GitLab instance (the default `oauth_extra_params={'url': 'gitlab.com'}`).\n",
    "\n",
    "### **Google**\n",
    "\n",
    "Google provides a guide about [configuring a OAuth application](https://developers.google.com/identity/protocols/oauth2/native-app). By default nothing except the `oauth_key` and `oauth_secret` are required but to access Google services you may also want to override the default `scope` via the `oauth_extra_params`.\n",
    "\n",
    "### **Okta**\n",
    "\n",
    "Okta provides a guide about [configuring OAuth2](https://developer.okta.com/docs/concepts/oauth-openid/). You must provide an `oauth_key` and `oauth_secret` but in most other ordinary setups you will also have to provide a `url` via the `oauth_extra_params` and if you have set up a custom authentication server (i.e. not 'default') with Okta you must also provide 'server', the `oauth_extra_params` should then look something like this: `{'server': 'custom', 'url': 'dev-***.okta.com'}`\n",
    "\n",
    "### Plugins\n",
    "\n",
    "The Panel OAuth providers are pluggable, in other words downstream libraries may define their own Tornado `RequestHandler` to be used with Panel. To register such a component the `setup.py` of the downstream package should register an entry_point that Panel can discover. To read more about entry points see the [Python documentation](https://packaging.python.org/specifications/entry-points/). A custom OAuth request handler in your library may be registered as follows:\n",
    "\n",
    "```python\n",
    "entry_points={\n",
    "    'panel.auth': [\n",
    "        \"custom = my_library.auth:MyCustomOAuthRequestHandler\"\n",
    "    ]\n",
    "}\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
