forked from jelhub/scimgateway
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
2213 lines (2065 loc) · 77.3 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>README</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style type="text/css">
/* RESET
=============================================================================*/
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video {
margin: 0;
padding: 0;
border: 0;
}
/* BODY
=============================================================================*/
body {
font-family: Helvetica, arial, freesans, clean, sans-serif;
font-size: 14px;
line-height: 1.6;
color: #333;
background-color: #fff;
padding: 20px;
max-width: 960px;
margin: 0 auto;
}
body>*:first-child {
margin-top: 0 !important;
}
body>*:last-child {
margin-bottom: 0 !important;
}
/* BLOCKS
=============================================================================*/
p, blockquote, ul, ol, dl, table, pre {
margin: 15px 0;
}
/* HEADERS
=============================================================================*/
h1, h2, h3, h4, h5, h6 {
margin: 20px 0 10px;
padding: 0;
font-weight: bold;
-webkit-font-smoothing: antialiased;
}
h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code {
font-size: inherit;
}
h1 {
font-size: 28px;
color: #000;
}
h2 {
font-size: 24px;
border-bottom: 1px solid #ccc;
color: #000;
}
h3 {
font-size: 18px;
}
h4 {
font-size: 16px;
}
h5 {
font-size: 14px;
}
h6 {
color: #777;
font-size: 14px;
}
body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child {
margin-top: 0;
padding-top: 0;
}
a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
margin-top: 0;
padding-top: 0;
}
h1+p, h2+p, h3+p, h4+p, h5+p, h6+p {
margin-top: 10px;
}
/* LINKS
=============================================================================*/
a {
color: #4183C4;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* LISTS
=============================================================================*/
ul, ol {
padding-left: 30px;
}
ul li > :first-child,
ol li > :first-child,
ul li ul:first-of-type,
ol li ol:first-of-type,
ul li ol:first-of-type,
ol li ul:first-of-type {
margin-top: 0px;
}
ul ul, ul ol, ol ol, ol ul {
margin-bottom: 0;
}
dl {
padding: 0;
}
dl dt {
font-size: 14px;
font-weight: bold;
font-style: italic;
padding: 0;
margin: 15px 0 5px;
}
dl dt:first-child {
padding: 0;
}
dl dt>:first-child {
margin-top: 0px;
}
dl dt>:last-child {
margin-bottom: 0px;
}
dl dd {
margin: 0 0 15px;
padding: 0 15px;
}
dl dd>:first-child {
margin-top: 0px;
}
dl dd>:last-child {
margin-bottom: 0px;
}
/* CODE
=============================================================================*/
pre, code, tt {
font-size: 12px;
font-family: Consolas, "Liberation Mono", Courier, monospace;
}
code, tt {
margin: 0 0px;
padding: 0px 0px;
white-space: nowrap;
border: 1px solid #eaeaea;
background-color: #f8f8f8;
border-radius: 3px;
}
pre>code {
margin: 0;
padding: 0;
white-space: pre;
border: none;
background: transparent;
}
pre {
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
border-radius: 3px;
}
pre code, pre tt {
background-color: transparent;
border: none;
}
kbd {
-moz-border-bottom-colors: none;
-moz-border-left-colors: none;
-moz-border-right-colors: none;
-moz-border-top-colors: none;
background-color: #DDDDDD;
background-image: linear-gradient(#F1F1F1, #DDDDDD);
background-repeat: repeat-x;
border-color: #DDDDDD #CCCCCC #CCCCCC #DDDDDD;
border-image: none;
border-radius: 2px 2px 2px 2px;
border-style: solid;
border-width: 1px;
font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
line-height: 10px;
padding: 1px 4px;
}
/* QUOTES
=============================================================================*/
blockquote {
border-left: 4px solid #DDD;
padding: 0 15px;
color: #777;
}
blockquote>:first-child {
margin-top: 0px;
}
blockquote>:last-child {
margin-bottom: 0px;
}
/* HORIZONTAL RULES
=============================================================================*/
hr {
clear: both;
margin: 15px 0;
height: 0px;
overflow: hidden;
border: none;
background: transparent;
border-bottom: 4px solid #ddd;
padding: 0;
}
/* TABLES
=============================================================================*/
table th {
font-weight: bold;
}
table th, table td {
border: 1px solid #ccc;
padding: 6px 13px;
}
table tr {
border-top: 1px solid #ccc;
background-color: #fff;
}
table tr:nth-child(2n) {
background-color: #f8f8f8;
}
/* IMAGES
=============================================================================*/
img {
max-width: 100%
}
</style>
</head>
<body>
<h1>SCIM Gateway</h1>
<p><a href="https://travis-ci.org/jelhub/scimgateway"><img src="https://travis-ci.org/jelhub/scimgateway.svg" alt="Build Status" /></a> <a href="https://www.npmjs.com/package/scimgateway"><img src="https://img.shields.io/npm/v/scimgateway.svg?style=flat-square&label=latest" alt="npm Version" /></a><a href="https://www.npmjs.com/package/scimgateway"><img src="https://img.shields.io/npm/dt/scimgateway.svg?style=flat-square" alt="npm Downloads" /></a> <a href="https://elshaug.xyz/md/scimgateway#disqus_thread"><img src="https://jelhub.github.io/images/chat.svg" alt="chat disqus" /></a> <a href="https://github.com/jelhub/scimgateway"><img src="https://img.shields.io/github/forks/jelhub/scimgateway.svg?style=social&label=Fork" alt="GitHub forks" /></a> </p>
<hr />
<p>Author: Jarle Elshaug </p>
<p>Validated through IdP's: </p>
<ul>
<li>CA Identity Manager</li>
<li>Microsoft Azure Active Directory </li>
<li>OneLogin </li>
<li>Okta<br />
Please let me know when you have deployed SCIM Gateway with your preffered IdP so list can be updated </li>
</ul>
<p>Latest news: </p>
<ul>
<li>Codebase moved from callback of h... to the the promise(d) land of async/await</li>
<li>Supports configuration by environments and external files</li>
<li>Health monitoring through "/ping" URL, and option for error notifications by email</li>
<li>Azure AD user provisioning including license management (e.g. Office 365), installed and configured within minutes!</li>
<li>Includes API Gateway for none SCIM/provisioning - becomes what you want it to become </li>
<li>Running SCIM Gateway as a Docker container </li>
</ul>
<h2>Overview</h2>
<p>With SCIM Gateway we could do user management by using REST based <a href="http://www.simplecloud.info/">SCIM</a> protocol. Gateway will then translate incoming SCIM requests and expose CRUD functionality (create, read, update and delete user/group) towards destinations using endpoint specific protocols. Gateway do not require SCIM to be used, it's also an API Gateway that could be used for other things than user provisioning. </p>
<p>SCIM Gateway is a standalone product, however this document shows how the gateway could be used by products like CA Identity Manager.</p>
<p>Using CA Identity Manager, we could setup one or more endpoints of type SCIM pointing to the gateway. Specific ports could then be used for each type of endpoint, and the SCIM Gateway would work like a "CA Connector Server" communicating with endpoints.</p>
<p><img src="https://jelhub.github.io/images/ScimGateway.svg" /></p>
<p>Instead of using IM-SDK for building our own integration for none supported endpoints, we can now build new integration based on SCIM Gateway plugins. SCIM Gateway works with IM as long as IM supports SCIM.</p>
<p>SCIM Gateway is based on the popular asynchronous event driven framework <a href="https://nodejs.dev/">Node.js</a> using JavaScript. It is firewall friendly using REST webservices. Runs on almost all operating systems, and may load balance between hosts (horizontal) and cpu's (vertical). Could even be uploaded and run as a cloud application.</p>
<p><strong>Following example plugins are included:</strong></p>
<ul>
<li>
<p><strong>Loki</strong> (NoSQL Document-Oriented Database)<br />
Gives a SCIM endpoint located on SCIM Gateway<br />
Demonstrates user provisioning towards document-oriented database<br />
Using <a href="http://lokijs.org">LokiJS</a> for a fast, in-memory document-oriented database (much like MongoDB/PouchDB)<br />
Default gives two predefined test users loaded using in-memory only (no persistence)<br />
Setting <code>{"persistence": true}</code> gives persistence file store (no test users)<br />
Example of a fully functional SCIM Gateway plugin
</p>
</li>
<li>
<p><strong>RESTful</strong> (REST Webservice)<br />
Demonstrates user provisioning towards REST-Based endpoint <br />
Using plugin "Loki" as a REST endpoint</p>
</li>
<li>
<p><strong>Forwardinc</strong> (SOAP Webservice)<br />
Demonstrates user provisioning towards SOAP-Based endpoint <br />
Using endpoint Forwardinc that comes with CA IM SDK (SDKWS) - <a href="https://docops.ca.com/ca-identity-manager/12-6-8/EN/programming/connector-programming-reference/sdk-sample-connectors/sdkws-sdk-web-services-connector/sdkws-sample-connector-build-requirements" title="wiki.ca.com">wiki.ca.com</a> <br />
Shows how to implement a highly configurable multi tenant or multi endpoint solution using <code>baseEntity</code> parameter
</p>
</li>
<li>
<p><strong>MSSQL</strong> (MSSQL Database)<br />
Demonstrates user provisioning towards MSSQL database
</p>
</li>
<li>
<p><strong>SAP HANA</strong> (SAP HANA Database)<br />
Demonstrates SAP HANA specific user provisioning
</p>
</li>
<li>
<p><strong>Azure AD</strong> (REST Webservices)<br />
Azure AD user provisioning including Azure license management (App Service plans) e.g. Office 365<br />
Using Microsoft Graph API<br />
Using customized SCIM attributes according to Microsoft Graph API<br />
Includes CA ConnectorXpress metafile for creating CA IM "Azure - ScimGateway" endpoint type
</p>
</li>
<li>
<p><strong>API</strong> (REST Webservices)<br />
Demonstrates API Gateway/plugin functionality using post/put/patch/get/delete<br />
None SCIM plugin, becomes what you want it to become.<br />
Endpoint complexity could be put in this plugin, and client could instead communicate through Gateway using your own simplified REST specification.<br />
One example of usage could be creation of tickets in ServiceDesk/HelpDesk and also the other way, closing a ticket could automatically approve/reject corresponding workflow in Identity Manager.
</p>
</li>
</ul>
<h2>Installation</h2>
<h4>Install Node.js</h4>
<p>Node.js is a prerequisite and have to be installed on the server. </p>
<p><a href="https://nodejs.org/en/download/">Download</a> the windows installer (.msi 64-bit) and install using default options. </p>
<h4>Install SCIM Gateway</h4>
<p>Open a command window (run as administrator)<br />
Create your own package directory e.g. C:\my-scimgateway and install SCIM Gateway within this package.</p>
<pre><code>mkdir c:\my-scimgateway
cd c:\my-scimgateway
npm init -y
npm install scimgateway --save
</code></pre>
<p>Please <strong>ignore any error messages</strong> unless soap WSSecurityCert functionality is needed in your custom plugin code. Module soap installation of optional dependency 'ursa' that also includes 'node-gyp' then needs misc. prerequisites to bee manually installed.</p>
<p><strong>c:\my-scimgateway</strong> will now be <code><package-root></code> </p>
<p>index.js, lib and config directories containing example plugins have been copied to your package from the original scimgateway package located under node_modules. </p>
<p>If internet connection is blocked, we could install on another machine and copy the scimgateway folder.</p>
<h4>Startup and verify default Loki plugin</h4>
<pre><code>node c:\my-scimgateway
Start a browser (note, IE does not support JSON content)
http://localhost:8880/ping
=> Health check with a "hello" response
http://localhost:8880/Users
http://localhost:8880/Groups
or
http://localhost:8880/Users?attributes=userName
http://localhost:8880/Groups?attributes=displayName
=> Logon using gwadmin/password and two users / four groups should be listed
http://localhost:8880/Users/bjensen
http://localhost:8880/Groups/Admins
=> Lists all attributes for specified user/group
"Ctrl + c" to stop the SCIM Gateway
</code></pre>
<p>For more functionality using browser (post/patch/delete) a REST extension/add-on is needed. </p>
<h4>Upgrade SCIM Gateway</h4>
<p>Not needed after a fresh install </p>
<p>Check if newer versions are available: </p>
<pre><code>cd c:\my-scimgateway
npm outdated
</code></pre>
<p>Lists current, wanted and latest version. No output on screen means we are running the latest version.</p>
<p>Upgrade to latest minor version: </p>
<pre><code>cd c:\my-scimgateway
npm install scimgateway
</code></pre>
<p>Note, always backup/copy C:\my-scimgateway before upgrading. Custom plugins and corresponding configuration files will not be affected. </p>
<p>To force a major upgrade (version x.*.* => y.*.*) that will brake compability with any existing custom plugins, we have to include the <code>@latest</code> suffix in the install command: <code>npm install scimgateway@latest</code></p>
<h2>Configuration</h2>
<p><strong>index.js</strong> defines one or more plugins to be started. We could comment out those we do not need. Default configuration only starts the loki plugin. </p>
<pre><code>const loki = require('./lib/plugin-loki')
// const restful = require('./lib/plugin-restful')
// const forwardinc = require('./lib/plugin-forwardinc')
// const mssql = require('./lib/plugin-mssql')
// const saphana = require('./lib/plugin-saphana') // prereq: npm install hdb --save
// const api = require('./lib/plugin-api')
// const azureAD = require('./lib/plugin-azure-ad')
</code></pre>
<p>Each endpoint plugin needs a JavaScript file (.js) and a configuration file (.json). <strong>They both must have the same naming prefix</strong>. For SAP Hana endpoint we have: </p>
<blockquote>
<p>lib\plugin-saphana.js<br />
config\plugin-saphana.json</p>
</blockquote>
<p>Edit specific plugin configuration file according to your needs.<br />
Below shows an example of config\plugin-saphana.json </p>
<pre><code>{
"scimgateway": {
"port": 8884,
"localhostonly": false,
"scim": {
"version": "1.1",
"customSchema": null,
"customUniqueAttrMapping" : {
"userName" : null,
"displayName": null
}
},
"loglevel": {
"file": "debug",
"console": "error"
},
"auth": {
"basic": {
"username": "gwadmin",
"password": "password"
},
"bearer": {
"token": null,
"jwt": {
"azure": {
"tenantIdGUID": null
},
"standard": {
"secret": null,
"publicKey": null,
"options": {
"issuer": null
}
}
}
}
},
"certificate": {
"key": null,
"cert": null,
"ca": null,
"pfx": {
"bundle": null,
"password": null
}
},
"emailOnError": {
"smtp": {
"enabled": false,
"host": null,
"port": 587,
"proxy": null,
"authenticate": true,
"username": null,
"password": null,
"sendInterval": 15,
"to": null,
"cc": null
}
}
},
"endpoint": {
"host": "hostname",
"port": 30015,
"username": "username",
"password": "password",
"saml_provider": "saml_provider_name"
}
}
</code></pre>
<p>Configuration file have two main JSON objects: <code>scimgateway</code> and <code>endpoint</code> </p>
<p>Definitions in <code>scimgateway</code> object have fixed attributes but values can be modified. This object is used by the core functionality of the SCIM Gateway. </p>
<p>Definitions in <code>endpoint</code> object are customized according to our plugin code. Plugin typically need this information for communicating with endpoint </p>
<ul>
<li>
<p><strong>port</strong> - Gateway will listen on this port number. Clients (e.g. Provisioning Server) will be using this port number for communicating with the gateway. For endpoint the port is the port number used by plugin for communicating with SAP Hana.
</p>
</li>
<li>
<p><strong>localhostonly</strong> - true or false. False means gateway accepts incoming requests from all clients. True means traffic from only localhost (127.0.0.1) is accepted (gateway must then be installed on the CA Connector Server).
</p>
</li>
<li>
<p><strong>scim.version</strong> - "1.1" or "2.0". Default is "1.1". For Azure AD as IdP "2.0" should be used.
</p>
</li>
<li>
<p><strong>scim.customSchema</strong> - filename of JSON file located in <code><package-root>\config\schemas</code> containing custom schema attributes, see configuration notes
</p>
</li>
<li>
<p><strong>scim.customUniqueAttrMapping</strong> - Option for replacing mandatory userName/displayName if IdP use other attributes
</p>
</li>
<li>
<p><strong>scim.customUniqueAttrMapping.userName</strong> - attribute replacing userName (User object)</p>
</li>
<li>
<p><strong>scim.customUniqueAttrMapping.displayName</strong> - attribute replacing displayName (Group object)</p>
</li>
<li>
<p><strong>loglevel.file</strong> - error, info or debug. Output to logfile <code>logs\plugin-saphana.log</code>
</p>
</li>
<li>
<p><strong>loglevel.console</strong> - error, info or debug. Output to stdout and errors to stderr.
</p>
</li>
<li>
<p><strong>auth</strong> - Contains one or more authentication/authorization methods used by clients for accessing gateway. <strong>Methods are disabled by setting corresponding attributes to null</strong>
</p>
</li>
<li>
<p><strong>auth.basic</strong> - Basic Authentication with <strong>username<strong>/</strong>password</strong>. Note, we set a clear text password and when gateway is started password will become encrypted and updated in the configuration file.
</p>
</li>
<li>
<p><strong>auth.bearer</strong> - Contains misc bearer token methods for authorization of client requests.
</p>
</li>
<li>
<p><strong>auth.bearer.token</strong> - Shared token/secret (supported by Azure). Clear text value will become encrypted when gateway is started.
</p>
</li>
<li>
<p><strong>auth.bearer.jwt</strong> - Contains misc JSON Web Token (JWT) methods for authorization.
</p>
</li>
<li>
<p><strong>auth.bearer.jwt.azure</strong> - JWT used by Azure SyncFabric. <strong>tenantIdGUID</strong> must be set to Azure Active Directory Tenant ID.
</p>
</li>
<li>
<p><strong>auth.bearer.jwt.standard</strong> - Standard JWT. Using <strong>secret</strong> or <strong>publicKey</strong> for signature verification. publicKey should be set to the filename of public key or certificate pem-file located in <code><package-root>\config\certs</code>. Clear text secret will become encrypted when gateway is started. <strong>options.issuer</strong> is mandatory. Other options may also be included according to jsonwebtoken npm package definition.
</p>
</li>
<li>
<p><strong>certificate</strong> - If not using SSL/TLS certificate, set "key", "cert" and "ca" to <strong>null</strong>. When using SSL/TLS, "key" and "cert" have to be defined with the filename corresponding to the primary-key and public-certificate. Both files must be located in the <code><package-root>\config\certs</code> directory e.g:
</p>
<pre><code>"certificate": {
"key": "key.pem",
"cert": "cert.pem",
"ca": null
}
</code></pre>
<p>Example of how to make a self signed certificate:
</p>
<pre><code>openssl req -nodes -newkey rsa:2048 -x509 -sha256 -days 3650 -keyout key.pem -out cert.pem -subj "/O=Testing/OU=SCIM Gateway/CN=<FQDN>" -config "<path>\openssl.cnf"
</code></pre>
<p><code><FQDN></code> is Fully Qualified Domain Name of the host having SCIM Gateway installed</p>
<p>Note, when using CA Provisioning, the "certificate authority - CA" also have to be imported on the Connector Server. For self-signed certificate CA and the certificate (public key) is the same.
</p>
<p>PFX / PKCS#12 bundle can be used instead of key/cert/ca e.g: </p>
<pre><code>"pfx": {
"bundle": "certbundle.pfx",
"password": "password"
}
</code></pre>
<p>Note, we should normally use certificate (https) for communicating with SCIM Gateway unless we install ScimGatway locally on the manager (e.g. on the CA Connector Server). When installed on the manager, we could use <code>http://localhost:port</code> or <code>http://127.0.0.1:port</code> which will not be passed down to the data link layer for transmission. We could then also set {"localhostonly": true}
</p>
</li>
<li>
<p><strong>emailOnError</strong> - Contains configuration for sending error notifications by email. Note, only the first error will be sent until sendInterval have passed </p>
</li>
<li><strong>emailOnError.smtp.enabled</strong> - true or false, value set to true will enable email notifications </li>
<li><strong>emailOnError.smtp.host</strong> - Mailserver e.g. "smtp.office365.com" </li>
<li><strong>emailOnError.smtp.port</strong> - Port used by mailserver e.g. 587, 25 or 465</li>
<li><strong>emailOnError.smtp.proxy</strong> - If using mailproxy e.g. "http://proxy-host:1234"</li>
<li><strong>emailOnError.smtp.authenticate</strong> - true or false, set to true will use username/password authentication</li>
<li><strong>emailOnError.smtp.username</strong> - Mail account for authentication and also the sender of the email, e.g. "user@outlook.com" </li>
<li><strong>emailOnError.smtp.password</strong> - Mail account password </li>
<li><strong>emailOnError.smtp.sendInterval</strong> - Mail notifications on error are deferred until sendInterval <strong>minutes</strong> have passed since the last notification. Default 15 minutes</li>
<li><strong>emailOnError.smtp.to</strong> - Comma separated list of recipients email addresses e.g: "someone@example.com"</li>
<li>
<p><strong>emailOnError.smtp.cc</strong> - Comma separated list of cc email addresses</p>
</li>
<li>
<p><strong>endpoint</strong> - Contains endpoint specific configuration according to our <strong>plugin code</strong>.
</p>
</li>
</ul>
<h4>Configuration notes</h4>
<ul>
<li>Setting environment variable <code>SEED</code> will override default password seeding logic. </li>
<li>All configuration can be set based on environment variables. Syntax will then be <code>"process.env.<ENVIRONMENT>"</code> where <code><ENVIRONMENT></code> is the environment variable used. E.g. scimgateway.port could have value "process.env.PORT", then using environment variable PORT.</li>
<li>
<p>All configuration can be set based on corresponding JSON-content in external file using plugin name as parent JSON object (supports also dot notation). Syntax will then be <code>"process.file.<path>"</code> where <code><path></code> is the file used. E.g. endpoint.password could have value "process.file./var/run/vault/secrets.json"
</p>
<p>Example:
</p>
<pre><code>{
"scimgateway": {
...
"port": "process.env.PORT",
...
"loglevel": {
"file": "process.env.LOG_LEVEL_FILE",
...
"auth": {
"basic": {
"username": "process.file./var/run/vault/secrets.json",
"password": "process.file./var/run/vault/secrets.json",
...
},
"endpoint": {
...
"username": "process.file./var/run/vault/secrets.json",
"password": "process.file./var/run/vault/secrets.json",
...
}
}
</code></pre>
<p>secrets.json for plugin-forwardinc - example #1:
</p>
<pre><code>{
"plugin-forwardinc": {
"scimgateway": {
"auth": {
"basic": {
"username": "gwadmin",
"password": "password"
}
}
},
"endpoint": {
"username": "superuser",
"password": "secret"
}
}
}
</code></pre>
<p>secrets.json for plugin-forwardinc - example #2 (dot notation):
</p>
<pre><code>{
"plugin-forwardinc.scimgateway.auth.basic.username": "gwadmin",
"plugin-forwardinc.scimgateway.auth.basic.password": "password",
"plugin-forwardinc.endpoint.username": "superuser",
"plugin-forwardinc.endpoint.password": "secret"
}
</code></pre>
</li>
<li>
<p>Custom schema attributes can be added by plugin configuration <code>scim.customSchema</code> having value set to filename of a JSON schema-file located in <code><package-root>/config/schemas</code> e.g:
</p>
<pre><code>"scim": {
"version": "1.1",
"customSchema": "plugin-forwardinc-schema.json"
},
</code></pre>
<p>JSON file have following syntax:
</p>
<pre><code>[
{
"name": "User",
"attributes": [...]
},
{
"name": "Group",
"attributes": [...]
}
]
</code></pre>
<p>Where array <code>attributes</code> contains custom attribute objects according to SCIM 1.1 or 2.0 spesification e.g:
</p>
<pre><code>"attributes": [
{
"name": "musicPreference",
"type": "string",
"multiValued": false,
"description": "Music Preferences",
"readOnly": false,
"required": false,
"caseExact": false
},
{
"name": "populations",
"type": "complex",
"multiValued": true,
"multiValuedAttributeChildName": "population",
"description": "Population array",
"readOnly": false,
"required": false,
"caseExact": false,
"subAttributes": [
{
"name": "value",
"type": "string",
"multiValued": false,
"description": "Population value",
"readOnly": false,
"required": true,
"caseExact": false
}
]
}
]
</code></pre>
<p>Note, custom schema attributes will be merged into core:1.0/2.0 schema, and names must not conflict with standard SCIM attribute names.</p>
</li>
</ul>
<h2>Manual startup</h2>
<p>Gateway can now be started from a command window running in administrative mode</p>
<p>3 ways to start:</p>
<pre><code>node c:\my-scimgateway
node c:\my-scimgateway\index.js
<package-root>node .
</code></pre>
<p><kbd>Ctrl</kbd>+<kbd>c</kbd> to stop </p>
<h2>Automatic startup - Windows Task Scheduler</h2>
<p>Start Windows Task Scheduler (taskschd.msc), right click on "Task Scheduler Library" and choose "Create Task" </p>
<pre><code>General tab:
-----------
Name = SCIM Gateway
User account = SYSTEM
Run with highest privileges
Triggers tab:
-------------
Begin the task = At startup
Actions tab:
------------
Action = Start a program
Program/script = c:\Program Files\nodejs\node.exe
Arguments = c:\my-scimgateway
Settings - tab:
---------------
Stop the task if runs longer than = Disabled (greyed out)
</code></pre>
<p>Verification:</p>
<ul>
<li>Right click task - <strong>Run</strong>, verify process node.exe (SCIM Gateway) can be found in the task manager (not the same as task scheduler). Also verify logfiles <code><pakage-root>\logs</code> </li>
<li>Right click task - <strong>End</strong>, verify process node.exe have been terminated and disappeared from task manager </li>
<li><strong>Reboot</strong> server and verify SCIM Gateway have been automatically started</li>
</ul>
<h2>Running as a isolated virtual Docker container</h2>
<p>On Linux systems we may also run SCIM Gateway as a Docker image (using docker-compose) </p>
<ul>
<li>
<p>Docker Pre-requisites:<br />
<strong>docker-ce<br />
docker-compose</strong></p>
</li>
<li>
<p>Install SCIM Gateway within your own package and copy provided docker files:</p>
<pre><code>mkdir /opt/my-scimgateway
cd /opt/my-scimgateway
npm init -y
npm install scimgateway --save
cp ./config/docker/* .
</code></pre>
<p><strong>docker-compose.yml</strong> <== Here is where you would set the exposed port and environment<br />
<strong>Dockerfile</strong> <== Main dockerfile<br />
<strong>DataDockerfile</strong> <== Handles volume mapping <br />
<strong>docker-compose-debug.yml</strong> <== Debugging
</p>
</li>
<li>
<p>Create a scimgateway user on your Linux VM.
</p>
<pre><code>adduser scimgateway
</code></pre>
</li>
<li>
<p>Create a directory on your VM host for the scimgateway configs:
</p>
<pre><code>mkdir /home/scimgateway/config
</code></pre>
</li>
<li>
<p>Copy your updated configuration file e.g. /opt/my-scimgateway/config/plugin-loki.json to /home/scimgateway/config. Use scp to perform the copy.</p>
<p>NOTE: /home/scimgateway/config is where all important configuration and loki datastore will reside outside of the running docker container. If you upgrade scimgateway you won't lose your configurations and data.</p>
</li>
<li>
<p>Build docker images and start it up
</p>
<pre><code>docker-compose up --build -d
</code></pre>
<p>NOTE: Add the -d flag to run the command above detached.
</p>
<p>Be sure to confirm that port 8880 is available with a simple http request</p>
<p>If using default plugin-loki and we have configured <code>{"persistence": true}</code>, we could confirm scimgateway created loki.db:</p>
<pre><code>su scimgateway
cd /home/scimgateway/config
ls loki.db
</code></pre>
</li>
</ul>
<p>To list running containers information:<br />
<code>docker ps</code></p>
<p>To list available images:<br />
<code>docker images</code></p>
<p>To view the logs:<br />
<code>docker logs scimgateway</code></p>
<p>To execute command within your running container:<br />
<code>docker exec scimgateway <bash command></code></p>
<p>To stop scimgateway:<br />
<code>docker-compose stop</code></p>
<p>To restart scimgateway:<br />
<code>docker-compose start</code></p>
<p>To debug running container (using Visual Studio Code):<br />
<code>docker-compose -f docker-compose.yml -f docker-compose-debug.yml up -d</code><br />
Start Visual Studio Code and follow <a href="https://code.visualstudio.com/docs/nodejs/nodejs-debugging">these</a> debugging instructions </p>
<p>To upgrade scimgateway docker image (remove the old stuff before running docker-compose up --build): </p>
<pre><code>docker rm scimgateway
docker rm $(docker ps -a -q); docker rmi $(docker images -q -f "dangling=true")
</code></pre>
<h2>CA Identity Manager as IdP using SCIM Gateway</h2>
<p>Using the CA Provisioning Manager we have to configure </p>
<p><code>Endpoint type = SCIM (DYN Endpoint)</code> </p>
<p>SCIM endpoint configuration example for Loki plugin (plugin-loki)</p>
<pre><code>Endpoint Name = Loki
User Name = gwadmin
Password = password
SCIM Authentication Method = HTTP Basic Authentication
SCIM Based URL = http://localhost:8880
or:
SCIM Based URL = http://localhost:8880/<baseEntity>
</code></pre>
<p>Username, password and port must correspond with plugin configuration file. For "Loki" plugin it will be <code>config\plugin-loki.json</code> </p>
<p>"SCIM Based URL" refer to the FQDN (or localhost) having SCIM Gateway installed. Portnumber must be included. Use HTTPS instead of HTTP if SCIM Gateway configuration includes certificates. </p>
<p>"baseEntity" is optional. This is a parameter used for multi tenant or multi endpoint solutions. We could create several endpoints having same base url with unique baseEntity. e.g: </p>
<p>http://localhost:8880/clientA<br />
http://localhost:8880/clientB</p>
<p>Each baseEntity should then be defined in the plugin configuration file with custom attributes needed. Please see examples in plugin-forwardinc.json</p>
<p>IM 12.6 SP7 (and above) also supports pagination for SCIM endpoint (data transferred in bulks - endpoint explore of users). Loki plugin supports pagination. Other plugin may ignore this setting. </p>
<h2>SCIM Gateway REST API</h2>
<pre><code>Create = POST http://example.com:8880/Users
(body contains the user information)
Update = PATCH http://example.com:8880/Users/<id>
(body contains the attributes to be updated)
Search/Read = GET http://example.com:8880/Users?userName eq
"userID"&attributes=<comma separated list of scim-schema defined attributes>
Search/explore all users:
GET http://example.com:8880/Users?attributes=userName
Delete = DELETE http://example.com:8880/Users/<id>
</code></pre>
<p>Discovery:</p>
<pre><code>GET http://example.com:8880/ServiceProviderConfigs
Specification compliance, authentication schemes, data models.
GET http://example.com:8880/Schemas
Introspect resources and attribute extensions.
</code></pre>
<p>Note: </p>
<ul>
<li>userName (mandatory) = UserID </li>
<li>id (mandatory) = Unique id. Could be set to the same as UserID but don't have to. </li>
</ul>
<h2>SAP Hana endpoint</h2>
<pre><code>Get all users (explore):
select USER_NAME from SYS.USERS where IS_SAML_ENABLED like 'TRUE';
Get a specific user:
select USER_NAME, USER_DEACTIVATED from SYS.USERS where USER_NAME like '<UserID>';
Create User:
CREATE USER <UserID> WITH IDENTITY '<UserID>' FOR SAML PROVIDER <SamlProvider>;
Delete user:
DROP USER <UserID>;
Modify user (enable user):
ALTER USER <UserID> ACTIVATE;
Modify user (disable user):
ALTER USER <UserID> DEACTIVATE;
</code></pre>
<p>Postinstallation: </p>
<pre><code>cd c:\my-scimgateway
npm install hdb --save
</code></pre>
<p>Only SAML users will be explored and managed</p>
<p>Supported template attributes: </p>
<ul>
<li>User Name (UserID)</li>
<li>Suspended (Enabled/Disabled) </li>
</ul>
<p>Currently no other attributes needed. Trying to update other attributes will then give an error message. <strong>The SCIM Provisioning template should therefore not include any other global user attribute references.</strong></p>
<p>SAP Hana converts UserID to uppercase. Provisioning use default lowercase. Provisioning template should therefore also convert to uppercase.</p>
<pre><code>User Name = %$$TOUPPER(%AC%)%
</code></pre>
<h2>Azure Active Directory endpoint</h2>
<p>Using plugin-azure-ad we could do user provisioning towards Azure AD including license management e.g. O365 </p>
<p>For testing purposes we could get an Azure free account and in addition the free Office 365 for testing license management through Azure.</p>
<p><strong>Azure AD prerequisites</strong> </p>
<ul>
<li>Logon to <a href="https://portal.azure.com">Azure</a> as global administrator </li>
<li>
Azure Active Directory - properties
<ul>
<li>Copy <strong>"Directory ID"</strong>
</li>
<li>or Azure Active Directory - Custom domain names (copy primary domain name)</li>
</ul>
</li>
<li>
Azure Active Directory - App registrations - New application registration
<ul>
<li>Name = newApp
</li>
<li>Application type = Web app API</li>
<li>Sign-on URL = http://localhost (not used)</li>
<li>Click "Create"</li>
</ul>
</li>
<li>
Click "newApp"
<ul>
<li>Copy <strong>"Application ID"</strong>
</li>
<li>
Required permissions - Windows Azure Active Directory
<ul>
<li>Enable "APPLICATION PERMISSIONS" (all application sub categories enabled)</li>
<li>Click "Save"</li>
</ul>
</li>
<li>
Keys
<ul>
<li>Key description = Key1</li>
<li>Duration = Never expires</li>
<li>Click "Save"</li>
<li>Copy Key1 <strong>"value"</strong>" (client secret)</li>
</ul>