//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
//
=== Set admin credentials

[WARNING]
The procedures below affects only the `Master` <<domains,domain>>; for other domains check <<domains-management,above>>.

The credentials are defined in the `core.properties` file; text encoding must be set to UTF-8:

* `security.adminUser` - administrator username (default `admin`)
* `security.adminPassword` - administrator password (default `password`)'s hashed value
* `security.adminPasswordAlgorithm` - algorithm to be used for hash evaluation (default `SSHA256`, also supported are
`SHA1`, `SHA256`, `SHA512`, `SMD5`, `SSHA1`, `SSHA512` and `BCRYPT`)
* `security.adminMfaSecret` - administrator MFA secret (no default)

.Generate SHA1 password value on GNU / Linux
====
The `sha1sum` command-line tool of http://www.gnu.org/software/coreutils/[GNU Core Utilities^] can be used as follows:
[source,bash]
....
echo -n "new_password" | sha1sum
....

Please beware that any shell special character must be properly escaped for the command above to produce the expected
hashed value.
====

.Generate SSHA256 password value on GNU / Linux
====
....
$ python3 pySSHA/ssha.py -p password -enc sha256 -s 666ac543 \
 | sed 's/{.*}//' | xargs echo -n | base64 -d | xxd -p | tr -d $'\n' | xargs echo
....

Several tools involved here:

* https://github.com/peppelinux/pySSHA-slapd[pySSHA-slapd^]
* http://man7.org/linux/man-pages/man1/xargs.1.html[xargs^]
* http://man7.org/linux/man-pages/man1/echo.1.html[echo^]
* http://man7.org/linux/man-pages/man1/base64.1.html[base64^]
* https://linux.die.net/man/1/xxd[xxd^]
* http://man7.org/linux/man-pages/man1/tr.1.html[tr^]

The command above will:

. generate a `SHA256` hash for input value `password` with suffixed salt `666ac543` (4 bytes in hex format), via `ssha.py`
. remove the `{SSHA256}` prefix from the generated value and newline, via `sed` and `xargs`
. since the generated value is Base64-encoded while Syncope requires Hexadecimal format, perform the required conversion
via `base64`, `xxd` and `tr`
. append newline to ease copy / paste, via `xargs` and `echo`
====

.Generate and set admin's MFA secret with http://curl.haxx.se/[curl^] 
====
The MFA secret shall be first generated by calling the dedicated REST endpoint as `anonymous`:
....
curl -o mfa.json -u anonymous:anonymousKey -X POST \
  http://localhost:9080/syncope/rest/mfa/admin
....

At this point the generated secret can be enrolled for `admin` via
.....
curl -u admin:password -X PUT -d @mfa.json -H "Content-Type: application/json" \
  http://localhost:9080/syncope/rest/mfa
.....

By doing so, the following message will be reported in the logs:

```
Generated MFA secret for admin. The property MUST be added to Core settings:
                             
  security.adminMfaSecret=XXXXXXXXXXXXXXX
```

Take note and add this property to `core.properties`.
====
