AuthPlug (auth_plug v1.5.2)

AuthPlug handles all our auth needs in just a handful of lines of code. Please see README.md for setup instructions.

Link to this section Summary

Functions

assign_jwt_to_socket/3 assigns a 'person' object containing information about the authenticated person to the socket in case the jwt parse is successful. It raises an error if jwt is not valid. This function is especially handy with LiveView. Invoke this as: socket = socket |> AuthPlug.assign_jwt_to_socket(&Phoenix.LiveView.assign_new/3, jwt) socket is the first argument to assign_jwt_to_socket/3 so it's chainable.

call/2 is invoked to handle each HTTP request which auth_plug protects. If the conn contains a valid JWT in Authentication Headers, jwt query parameter or Phoenix Session, then continue to the protected route, else redirect to the auth_url with the referer set as the continuation URL.

end_session/1 makes an HTTP Request to the auth_url to end the session. This in turn makes the update on the auth app to update the session.end so the owner of the "consumer" app knows when the person logged out. end_session/1 is invoked by AuthPlug.logout/1 (above) which will likely be the function called in practice.

get_auth_url/2 returns a string representing the auth url. The first parameter is conn, the second is optional and represents the endpoint in your application where the auth application will redirect to after authentication. By default the second parameter value is conn.request_path which represents the current path.

init/1 initialises the options passed in and makes them available in the lifecycle of the call/2 invocation (below). We pass in the auth_url key/value with the URL of the Auth service to redirect to if session is invalid/expired.

logout/1 does exactly what you expect; logs the person out of your app. receives a conn (Plug.Conn) and unsets the session. This is super-useful in testing as we can easily reset a session.

Link to this section Functions

Link to this function

assign_jwt_to_socket(socket, assign_new, jwt)

assign_jwt_to_socket/3 assigns a 'person' object containing information about the authenticated person to the socket in case the jwt parse is successful. It raises an error if jwt is not valid. This function is especially handy with LiveView. Invoke this as: socket = socket |> AuthPlug.assign_jwt_to_socket(&Phoenix.LiveView.assign_new/3, jwt) socket is the first argument to assign_jwt_to_socket/3 so it's chainable.

Link to this function

call(conn, options)

call/2 is invoked to handle each HTTP request which auth_plug protects. If the conn contains a valid JWT in Authentication Headers, jwt query parameter or Phoenix Session, then continue to the protected route, else redirect to the auth_url with the referer set as the continuation URL.

Link to this function

create_jwt_session(conn, claims)

Link to this function

end_session(conn)

end_session/1 makes an HTTP Request to the auth_url to end the session. This in turn makes the update on the auth app to update the session.end so the owner of the "consumer" app knows when the person logged out. end_session/1 is invoked by AuthPlug.logout/1 (above) which will likely be the function called in practice.

Link to this function

end_session_auth(auth_url)

Link to this function

get_auth_url(conn, redirect_to \\ nil)

get_auth_url/2 returns a string representing the auth url. The first parameter is conn, the second is optional and represents the endpoint in your application where the auth application will redirect to after authentication. By default the second parameter value is conn.request_path which represents the current path.

examples

Examples

iex> AuthPlug.get_auth_url(conn) "https://dwylauth.herokuapp.com/?referer=https://www.example.com/&auth_client_id=123123"

iex> AuthPlug.get_auth_url(conn, "/mypage) "https://dwylauth.herokuapp.com/?referer=https://www.example.com/mypage&auth_client_id=123123"

init/1 initialises the options passed in and makes them available in the lifecycle of the call/2 invocation (below). We pass in the auth_url key/value with the URL of the Auth service to redirect to if session is invalid/expired.

logout/1 does exactly what you expect; logs the person out of your app. receives a conn (Plug.Conn) and unsets the session. This is super-useful in testing as we can easily reset a session.