Skip to content

Commit a0804db

Browse files
ucarionucarion
committed
LICENSE, README
1 parent 3ae94da commit a0804db

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Ssoready.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
![](https://i.imgur.com/oaig6Au.gif)
2+
3+
# SSOReady Example App: PHP + Laravel with SAML
4+
5+
This repo contains a minimal example app built with PHP and Laravel that
6+
supports [SAML](https://ssoready.com/docs/saml/saml-quickstart) using the
7+
[SSOReady PHP SDK](https://github.com/ssoready/ssoready-php).
8+
9+
[SSOReady](https://github.com/ssoready/ssoready) is an open-source way to add
10+
SAML and SCIM support to your application.
11+
12+
## Running it yourself
13+
14+
To check out this repo yourself, you'll need a working installation of PHP and
15+
Composer. Then, run:
16+
17+
```
18+
git clone https://github.com/ssoready/ssoready-example-app-php-laravel-saml
19+
cd ssoready-example-app-php-laravel-saml/app
20+
21+
composer install
22+
composer run dev
23+
```
24+
25+
Then, visit http://localhost:8000.
26+
27+
## How it works
28+
29+
![](https://i.imgur.com/DkcXB4F.png)
30+
31+
There are two steps involved in implementing SAML:
32+
33+
1. Initiating SAML logins, where you redirect the user to their corporate
34+
identity provider
35+
2. Handling SAML logins, where you log the user in after they've authenticated
36+
using SAML.
37+
38+
### Initiating SAML logins
39+
40+
In this demo app, initiating SAML logins happens from the `/saml-redirect`
41+
endpoint:
42+
43+
```php
44+
Route::get('/saml-redirect', function(Request $request) use ($ssoready) {
45+
$redirectUrl = $ssoready->saml->getSAMLRedirectURL(new SSOReady\Saml\Requests\GetSamlRedirectUrlRequest([
46+
// convert '[email protected]' into 'example.com'.
47+
'organizationExternalId' => explode('@', $request->input('email'))[1],
48+
]))->redirectUrl;
49+
50+
return redirect($redirectUrl);
51+
});
52+
```
53+
54+
You initiate a SAML login by calling
55+
[`saml->getSAMLRedirectURL`](https://ssoready.com/docs/api-reference/saml/get-saml-redirect-url)
56+
and redirecting to the returned URL.
57+
58+
The
59+
[`organizationExternalId`](https://ssoready.com/docs/api-reference/saml/get-saml-redirect-url#request.body.organizationExternalId)
60+
is to tell SSOReady which customer's corporate identity provider you want to
61+
redirect to. In the demo app, we use `example.com` or `example.org` as the
62+
[organization external
63+
ID](https://ssoready.com/docs/ssoready-concepts/organizations#organization-external-id).
64+
65+
### Handling SAML logins
66+
67+
After your user finishes authenticating over SAML, SSOReady will redirect them
68+
back to your application. In this demo app, that callback URL is configured to
69+
be `http://localhost:8000/ssoready-callback`, so you'll get requests that look
70+
like this:
71+
72+
```
73+
GET http://localhost:8000/ssoready-callback?saml_access_code=saml_access_code_...
74+
```
75+
76+
Here's how the demo app handles those requests:
77+
78+
```php
79+
Route::get('/ssoready-callback', function(Request $request) use ($ssoready) {
80+
$email = $ssoready->saml->redeemSamlAccessCode(new SSOReady\Saml\Requests\RedeemSamlAccessCodeRequest([
81+
'samlAccessCode' => $request->input('saml_access_code'),
82+
]))->email;
83+
84+
// upsert a user by email
85+
$user = User::firstOrCreate(
86+
['email' => $email],
87+
['email' => $email, 'name' => $email, 'password' => ''],
88+
);
89+
Auth::login($user); // log in as that user
90+
return redirect('/');
91+
});
92+
```
93+
94+
You handle a SAML login by calling
95+
[`saml->redeemSamlAccessCode`](https://ssoready.com/docs/api-reference/saml/redeem-saml-access-code)
96+
with the `saml_access_code` query parameter value, and logging the user in from
97+
the `email` SSOReady returns to you.
98+
99+
And that's it! That's all the code you have to write to add SAML support to your
100+
application.
101+
102+
### Configuring SSOReady
103+
104+
To make this demo app work out of the box, we did some work for you. You'll need
105+
to follow these steps yourself when you integrate SAML into your app.
106+
107+
The steps we took were:
108+
109+
1. We signed up for SSOReady at https://app.ssoready.com.
110+
2. We created an
111+
[environment](https://ssoready.com/docs/ssoready-concepts/environments), and
112+
configured its [redirect
113+
URL](https://ssoready.com/docs/ssoready-concepts/environments#redirect-url)
114+
to be `http://localhost:8000/ssoready-callback`.
115+
3. We created an [API
116+
key](https://ssoready.com/docs/ssoready-concepts/environments#api-keys).
117+
Because this is a demo app, we hard-coded the API key. In production apps,
118+
you'll instead put that API key secret into an `SSOREADY_API_KEY` environment
119+
variable on your backend.
120+
4. We created two
121+
[organizations](https://ssoready.com/docs/ssoready-concepts/organizations),
122+
both of which use [DummyIDP.com](https://ssoready.com/docs/dummyidp) as their
123+
"corporate" identity provider:
124+
125+
- One organization has [external
126+
ID](https://ssoready.com/docs/ssoready-concepts/organizations#organization-external-id)
127+
`example.com` and a [domain
128+
whitelist](https://ssoready.com/docs/ssoready-concepts/organizations#domains)
129+
of just `example.com`.
130+
- The second organization has extnernal ID `example.org` and domain whitelist
131+
`example.org`.
132+
133+
In production, you'll create a separate organization for each company that wants
134+
SAML. Your customers won't be using [DummyIDP.com](https://dummyidp.com); that's
135+
just a SAML testing service that SSOReady offers for free. Your customers will
136+
instead be using vendors including
137+
[Okta](https://www.okta.com/products/single-sign-on-customer-identity/),
138+
[Microsoft
139+
Entra](https://www.microsoft.com/en-us/security/business/microsoft-entra), and
140+
[Google Workspace](https://workspace.google.com/). From your code's perspective,
141+
those vendors will all look exactly the same.
142+
143+
## Next steps
144+
145+
This demo app gives you a crash-course demo of how to implement SAML end-to-end.
146+
If you want to see how this all fits together in greater detail, with every step
147+
described in greater detail, check out the [SAML
148+
quickstart](https://ssoready.com/docs/saml/saml-quickstart) or the rest of the
149+
[SSOReady docs](https://ssoready.com/docs).

0 commit comments

Comments
 (0)