streamlit-nightly 1.41.2.dev20250117__py2.py3-none-any.whl → 1.41.2.dev20250124__py2.py3-none-any.whl

streamlit/user_info.py

@@ -48,14 +48,229 @@ AUTH_LOGOUT_ENDPOINT: Final = "/auth/logout"
 
 @gather_metrics("login")
 def login(provider: str | None = None) -> None:
-    """Initiate the login for the given provider.
+    """Initiate the login flow for the given provider.
+
+    This command redirects the user to an OpenID Connect (OIDC) provider. After
+    the user authenticates their identity, they are redirected back to the
+    home page of your app. Streamlit stores a cookie with the user's identity
+    information in the user's browser . You can access the identity information
+    through |st.experimental_user|_. Call ``st.logout()`` to remove the cookie
+    and start a new session.
+
+    You can use any OIDC provider, including Google, Microsoft, Okta, and more.
+    You must configure the provider through secrets management. Although OIDC
+    is an extension of OAuth 2.0, you can't use generic OAuth providers.
+    Streamlit parses the user's identity token and surfaces its attributes in
+    ``st.experimental_user``. If the provider returns an access token, that
+    token is ignored. Therefore, this command will not allow your app to act on
+    behalf of a user in a secure system.
+
+    For all providers, there are two shared settings, ``redirect_uri`` and
+    ``cookie_secret``, which you must specify in an ``[auth]`` dictionary
+    in ``secrets.toml``. Other settings must be defined as described in the
+    ``provider`` parameter.
+
+    - ``redirect_uri`` is your app's absolute URL with the pathname
+      ``oauth2callback``. For local development using the default port, this is
+      ``http://localhost:8501/oauth2callback``.
+    - ``cookie_secret`` should be a strong, randomly generated secret.
+
+    In addition to the shared settings, the following settings are required:
+
+    - ``client_id``
+    - ``client_secret``
+    - ``server_metadata_url``
+
+    For a complete list of OIDC parameters, see `OpenID Connect Core
+    <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`_ and
+    your provider's documentation. By default, Streamlit sets
+    ``scope="openid profile email"`` and ``prompt="select_account"``. You can
+    change these and other OIDC parameters by passing a dictionary of settings
+    to ``client_kwargs``. ``state`` and ``nonce``, which are used for
+    security, are handled automatically and don't need to be specified. For
+    more information, see Example 4.
+
+    .. Important::
+        - You must install ``Authlib>=1.3.2`` to use this command.
+        - Your authentication configuration is dependent on your host location.
+          When you deploy your app, remember to update your ``redirect_uri``
+          within your app and your provider.
+        - All URLs declared in the settings must be absolute (i.e., begin with
+          ``http://`` or ``https://``).
+        - Streamlit automatically enables CORS and XSRF protection when you
+          configure authentication in ``secrets.toml``. This takes precedence
+          over configuration options in ``config.toml``.
+        - If a user is logged into your app and opens a new tab in the same
+          browser, they will automatically be logged in to the new session with
+          the same account.
+        - If a user closes your app without logging out, the identity cookie
+          will expire after 30 days.
+        - For security reasons, authentication is not supported for embedded
+          apps.
+
+    .. |st.experimental_user| replace:: ``st.experimental_user``
+    .. _st.experimental_user: https://docs.streamlit.io/develop/api-reference/utilities/st.experimental_user
 
     Parameters
     ----------
-    provider : str or None
-        The provider to use for login. This value must match the name of a
-        provider configured in the app's auth section of ``secrets.toml`` file.
-        If None, the default provider in the auth section will be used.
+    provider: str or None
+        The name of your provider configuration to use for login.
+
+        If ``provider`` is ``None`` (default), Streamlit will use all settings
+        in the ``[auth]`` dictionary within your app's ``secrets.toml`` file.
+        Otherwise, use an ``[auth.{provider}]`` dictionary for the named
+        provider, as shown in the examples that follow. When you pass a string
+        to ``provider``, Streamlit will use ``redirect_uri`` and
+        ``cookie_secret``, while ignoring any other values in the ``[auth]``
+        dictionary.
+
+    Examples
+    --------
+
+    **Example 1: Use an unnamed default identity provider**
+
+    If you do not specify a name for your provider, specify all settings within
+    the ``[auth]`` dictionary of your ``secrets.toml`` file. The following
+    example configures Google as the default provider. For information about
+    using OIDC with Google, see `Google Identity
+    <https://developers.google.com/identity/openid-connect/openid-connect>`_.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [auth]
+    >>> redirect_uri = "http://localhost:8501/oauth2callback"
+    >>> cookie_secret = "xxx"
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = (
+    ...     "https://accounts.google.com/.well-known/openid-configuration"
+    ... )
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if not st.experimental_user.is_logged_in:
+    >>>     if st.button("Log in"):
+    >>>         st.login()
+    >>> else:
+    >>>     if st.button("Log out"):
+    >>>         st.logout()
+    >>>     st.write(f"Hello, {st.experimental_user.name}!")
+
+    **Example 2: Use a named identity provider**
+
+    If you specify a name for your provider, save the shared settings in the
+    ``[auth]`` dictionary of your ``secrets.toml`` file, and save the other
+    settings in an ``[auth.{provider}]`` dictionary, where ``{provider}`` is
+    the name of your provider. The following example configures Microsoft as
+    the provider. The example uses ``provider="microsoft"``, but you can use
+    any name. This name is internal to Streamlit and is used to match the login
+    command to its configuration. For information about using OIDC with
+    Microsoft, see `Microsoft Entra ID
+    <https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings>`_.
+    To configure your ``{tenant}`` value in ``server_metadata_url``, see
+    `Microsoft identity platform
+    <https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri>`_.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [auth]
+    >>> redirect_uri = "http://localhost:8501/oauth2callback"
+    >>> cookie_secret = "xxx"
+    >>>
+    >>> [auth.microsoft]
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if not st.experimental_user.is_logged_in:
+    >>>     st.login("microsoft")
+    >>> else:
+    >>>     st.write(f"Hello, {st.experimental_user.name}!")
+
+    **Example 3: Use multiple, named providers**
+
+    If you want to give your users a choice of authentication methods,
+    configure multiple providers and give them each a unique name. The
+    following example lets users choose between Okta and Microsoft to log in.
+    Always check with your identity provider to understand the structure of
+    their identity tokens because the returned fields may differ. Remember to
+    set ``{tenant}`` and ``{subdomain}`` in ``server_metadata_url`` for
+    Microsoft and Okta, respectively.
+
+    >>> [auth]
+    >>> redirect_uri = "http://localhost:8501/oauth2callback"
+    >>> cookie_secret = "xxx"
+    >>>
+    >>> [auth.microsoft]
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration"
+    >>>
+    >>> [auth.okta]
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = (
+    ...     "https://{subdomain}.okta.com/.well-known/openid-configuration"
+    ... )
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if not st.experimental_user.is_logged_in:
+    >>>     st.header("Log in:")
+    >>>     if st.button("Microsoft"):
+    >>>         st.login("microsoft")
+    >>>     if st.button("Okta"):
+    >>>         st.login("okta")
+    >>> else:
+    >>>     if st.button("Log out"):
+    >>>         st.logout()
+    >>>     st.write(f"Hello, {st.experimental_user.name}!")
+
+    **Example 4: Change the default connection settings**
+
+    ``prompt="select_account"`` may be treated differently by some
+    providers when a user is already logged into their account. If a user is
+    logged into their Google or Microsoft account from a previous session, the
+    provider will prompt them to select the account they want to use, even if
+    it's the only one. However, if the user is logged into their Okta or Auth0
+    account from a previous session, the account will automatically be
+    selected. ``st.logout()`` does not clear a user's related cookies. To force
+    users to log in every time, use ``prompt="login"`` as described in Auth0's
+    `Customize Signup and Login Prompts
+    <https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts>`_.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [auth]
+    >>> redirect_uri = "http://localhost:8501/oauth2callback"
+    >>> cookie_secret = "xxx"
+    >>>
+    >>> [auth.auth0]
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = (
+    ...     "https://{account}.{region}.auth0.com/.well-known/openid-configuration"
+    ... )
+    >>> client_kwargs = { "prompt" = "login" }
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> if st.button("Log in"):
+    >>>     st.login("auth0")
+    >>> if st.experimental_user.is_logged_in:
+    >>>     if st.button("Log out"):
+    >>>         st.logout()
+    >>>     st.write(f"Hello, {st.experimental_user.name}!)
+
     """
     if provider is None:
         provider = "default"
@@ -75,7 +290,47 @@ def login(provider: str | None = None) -> None:
 
 @gather_metrics("logout")
 def logout() -> None:
-    """Logout the current user."""
+    """Logout the current user.
+
+    This command removes the user's information from ``st.experimental_user``,
+    deletes their identity cookie, and redirects them back to your app's home
+    page. This creates a new session.
+
+    If the user has multiple sessions open in the same browser,
+    ``st.experimental_user`` will not be cleared in any other session.
+    ``st.experimental_user`` only reads from the identity cookie at the start
+    of a session. After a session is running, you must call ``st.login()`` or
+    ``st.logout()`` within that session to update ``st.experimental_user``.
+
+    .. Note::
+        This does not log the user out of their underlying account from the
+        identity provider.
+
+    Example
+    -------
+    ``.streamlit/secrets.toml``:
+
+    >>> [auth]
+    >>> redirect_uri = "http://localhost:8501/oauth2callback"
+    >>> cookie_secret = "xxx"
+    >>> client_id = "xxx"
+    >>> client_secret = "xxx"
+    >>> server_metadata_url = (
+    ...     "https://accounts.google.com/.well-known/openid-configuration"
+    ... )
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if not st.experimental_user.is_logged_in:
+    >>>     if st.button("Log in"):
+    >>>         st.login()
+    >>> else:
+    >>>     if st.button("Log out"):
+    >>>         st.logout()
+    >>>     st.write(f"Hello, {st.experimental_user.name}!")
+    """
     context = _get_script_run_ctx()
     if context is not None:
         context.user_info.clear()
@@ -115,15 +370,113 @@ def _get_user_info() -> UserInfo:
 
 class UserInfoProxy(Mapping[str, Union[str, bool, None]]):
     """
-    A read-only, dict-like object for accessing information about current user.
+    A read-only, dict-like object for accessing information about the current
+    user.
 
-    ``st.experimental_user`` is dependent on the host platform running the
+    ``st.experimental_user`` is dependent on the host platform running your
     Streamlit app. If the host platform has not configured the function, it
-    will behave as it does in a locally running app.
+    will behave as in a locally running app.
+
+    When authentication is configured in ``secrets.toml``, Streamlit will parse
+    the OpenID Connect (OIDC) identity token and copy the attributes to
+    ``st.experimental_user``. Check your provider's documentation for their
+    available attributes (known as claims).
 
-    Properties can be accessed via key or attribute notation. For example,
-    ``st.experimental_user["email"]`` or ``st.experimental_user.email``.
+    When authentication is not configured, ``st.experimental_user`` has no
+    attributes.
 
+    You can access values via key or attribute notation. For example, use
+    ``st.experimental_user["email"]`` or ``st.experimental_user.email`` to
+    access the ``email`` attribute.
+
+    .. Important::
+        Identity tokens include an issuance and expiration time. Streamlit does
+        not implicitly check these. If you want to automatically expire a
+        user's authentication, check these values manually and programmatically
+        log out your user (``st.logout()``) when needed.
+
+    Attributes
+    ----------
+    is_logged_in: bool
+        Whether a user is logged in. For a locally running app, this attribute
+        is only available when authentication (``st.login()``) is configured in
+        ``secrets.toml``. Otherwise, it does not exist.
+
+    Examples
+    --------
+    **Example 1: Google's identity token**
+
+    If you configure a basic Google OIDC connection as shown in Example 1 of
+    ``st.login()``, the following data is available in
+    ``st.experimental_user``. Streamlit adds the ``is_logged_in`` attribute.
+    Additional attributes may be available depending on the configuration of
+    the user's Google account. For more information about Google's identity
+    tokens, see `Obtain user information from the ID token
+    <https://developers.google.com/identity/openid-connect/openid-connect#obtainuserinfo>`_
+    in Google's docs.
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if st.experimental_user.is_logged_in:
+    >>>     st.write(st.experimental_user)
+
+    Displayed data when a user is logged in:
+
+    >>> {
+    >>>     "is_logged_in":true
+    >>>     "iss":"https://accounts.google.com"
+    >>>     "azp":"{client_id}.apps.googleusercontent.com"
+    >>>     "aud":"{client_id}.apps.googleusercontent.com"
+    >>>     "sub":"{unique_user_id}"
+    >>>     "email":"{user}@gmail.com"
+    >>>     "email_verified":true
+    >>>     "at_hash":"{access_token_hash}"
+    >>>     "nonce":"{nonce_string}"
+    >>>     "name":"{full_name}"
+    >>>     "picture":"https://lh3.googleusercontent.com/a/{content_path}"
+    >>>     "given_name":"{given_name}"
+    >>>     "family_name":"{family_name}"
+    >>>     "iat":{issued_time}
+    >>>     "exp":{expiration_time}
+    >>> }
+
+    **Example 2: Microsoft's identity token**
+
+    If you configure a basic Microsoft OIDC connection as shown in Example 2 of
+    ``st.login()``, the following data is available in
+    ``st.experimental_user``. For more information about Microsoft's identity
+    tokens, see `ID token claims reference
+    <https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference>`_
+    in Microsoft's docs.
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>>
+    >>> if st.experimental_user.is_logged_in:
+    >>>     st.write(st.experimental_user)
+
+    Displayed data when a user is logged in:
+
+    >>> {
+    >>>     "is_logged_in":true
+    >>>     "ver":"2.0"
+    >>>     "iss":"https://login.microsoftonline.com/{tenant_id}/v2.0"
+    >>>     "sub":"{application_user_id}"
+    >>>     "aud":"{application_id}"
+    >>>     "exp":{expiration_time}
+    >>>     "iat":{issued_time}
+    >>>     "nbf":{start_time}
+    >>>     "name":"{full_name}"
+    >>>     "preferred_username":"{username}"
+    >>>     "oid":"{user_GUID}"
+    >>>     "email":"{email}"
+    >>>     "tid":"{tenant_id}"
+    >>>     "nonce":"{nonce_string}"
+    >>>     "aio":"{opaque_string}"
+    >>> }
     """
 
     def __getitem__(self, key: str) -> str | bool | None:

{streamlit_nightly-1.41.2.dev20250117.dist-info → streamlit_nightly-1.41.2.dev20250124.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: streamlit-nightly
-Version: 1.41.2.dev20250117
+Version: 1.41.2.dev20250124
 Summary: A faster way to build and share data apps
 Home-page: https://streamlit.io
 Author: Snowflake Inc